<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="copyright" content="Copyright &#169; Stuart Rackham" />
<meta name="generator" content="AsciiDoc 8.6.5" />
<title>AsciiDoc User Guide</title>
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */

/* Default font. */
body {
  font-family: Georgia,serif;
}

/* Title font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
#toctitle,
#author, #revnumber, #revdate, #revremark,
#footer {
  font-family: Arial,Helvetica,sans-serif;
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}
h5 {
  font-size: 1.0em;
}

div.sectionbody {
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}
ul > li     { color: #aaa; }
ul > li > * { color: black; }

pre {
  padding: 0;
  margin: 0;
}

#author {
  color: #527bbd;
  font-weight: bold;
  font-size: 1.1em;
}
#email {
}
#revnumber, #revdate, #revremark {
}

#footer {
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid #dddddd;
  border-left: 4px solid #f0f0f0;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid #dddddd;
  border-left: 5px solid #f0f0f0;
  background: #f8f8f8;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #f0f0f0;
  color: #777777;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > pre.content {
  font-family: inherit;
  font-size: inherit;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}

div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}

div.colist td {
  padding-right: 0.5em;
  padding-bottom: 0.3em;
  vertical-align: top;
}
div.colist td img {
  margin-top: 0.3em;
}

@media print {
  #footer-badges { display: none; }
}

#toc {
  margin-bottom: 2.5em;
}

#toctitle {
  color: #527bbd;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}

span.aqua { color: aqua; }
span.black { color: black; }
span.blue { color: blue; }
span.fuchsia { color: fuchsia; }
span.gray { color: gray; }
span.green { color: green; }
span.lime { color: lime; }
span.maroon { color: maroon; }
span.navy { color: navy; }
span.olive { color: olive; }
span.purple { color: purple; }
span.red { color: red; }
span.silver { color: silver; }
span.teal { color: teal; }
span.white { color: white; }
span.yellow { color: yellow; }

span.aqua-background { background: aqua; }
span.black-background { background: black; }
span.blue-background { background: blue; }
span.fuchsia-background { background: fuchsia; }
span.gray-background { background: gray; }
span.green-background { background: green; }
span.lime-background { background: lime; }
span.maroon-background { background: maroon; }
span.navy-background { background: navy; }
span.olive-background { background: olive; }
span.purple-background { background: purple; }
span.red-background { background: red; }
span.silver-background { background: silver; }
span.teal-background { background: teal; }
span.white-background { background: white; }
span.yellow-background { background: yellow; }

span.big { font-size: 2em; }
span.small { font-size: 0.6em; }

span.underline { text-decoration: underline; }
span.overline { text-decoration: overline; }
span.line-through { text-decoration: line-through; }


/*
 * xhtml11 specific
 *
 * */

tt {
  font-family: monospace;
  font-size: inherit;
  color: navy;
}

div.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-weight: bold;
  color: #527bbd;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


/*
 * html5 specific
 *
 * */

.monospaced {
  font-family: monospace;
  font-size: inherit;
  color: navy;
}

table.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
thead, p.tableblock.header {
  font-weight: bold;
  color: #527bbd;
}
p.tableblock {
  margin-top: 0;
}
table.tableblock {
  border-width: 3px;
  border-spacing: 0px;
  border-style: solid;
  border-color: #527bbd;
  border-collapse: collapse;
}
th.tableblock, td.tableblock {
  border-width: 1px;
  padding: 4px;
  border-style: solid;
  border-color: #527bbd;
}

table.tableblock.frame-topbot {
  border-left-style: hidden;
  border-right-style: hidden;
}
table.tableblock.frame-sides {
  border-top-style: hidden;
  border-bottom-style: hidden;
}
table.tableblock.frame-none {
  border-style: hidden;
}

th.tableblock.halign-left, td.tableblock.halign-left {
  text-align: left;
}
th.tableblock.halign-center, td.tableblock.halign-center {
  text-align: center;
}
th.tableblock.halign-right, td.tableblock.halign-right {
  text-align: right;
}

th.tableblock.valign-top, td.tableblock.valign-top {
  vertical-align: top;
}
th.tableblock.valign-middle, td.tableblock.valign-middle {
  vertical-align: middle;
}
th.tableblock.valign-bottom, td.tableblock.valign-bottom {
  vertical-align: bottom;
}


/*
 * manpage specific
 *
 * */

body.manpage h1 {
  padding-top: 0.5em;
  padding-bottom: 0.5em;
  border-top: 2px solid silver;
  border-bottom: 2px solid silver;
}
body.manpage h2 {
  border-style: none;
}
body.manpage div.sectionbody {
  margin-left: 3em;
}

@media print {
  body.manpage div#toc { display: none; }
}
</style>
<style type="text/css">
/* slidy.css

   Copyright (c) 2005-2010 W3C (MIT, ERCIM, Keio), All Rights Reserved.
   W3C liability, trademark, document use and software licensing
   rules apply, see:

   http://www.w3.org/Consortium/Legal/copyright-documents
   http://www.w3.org/Consortium/Legal/copyright-software
*/

/*
   SJR: 2010-09-29: Modified for AsciiDoc slidy backend.
   Mostly just commented out stuff that is handled by AsciiDoc's CSS files.
*/

body
{
  margin: 0 0 0 0;
  padding: 0 0 0 0;
  width: 100%;
  height: 100%;
  color: black;
  background-color: white;
/*
  font-family: "Gill Sans MT", "Gill Sans", GillSans, sans-serif;
*/
  font-size: 14pt;
}

div.toolbar {
  position: fixed; z-index: 200;
  top: auto; bottom: 0; left: 0; right: 0;
  height: 1.2em; text-align: right;
  padding-left: 1em;
  padding-right: 1em;
  font-size: 60%;
  color: red;
  background-color: rgb(240,240,240);
  border-top: solid 1px rgb(180,180,180);
}

div.toolbar span.copyright {
  color: black;
  margin-left: 0.5em;
}

div.initial_prompt {
  position: absolute;
  z-index: 1000;
  bottom: 1.2em;
  width: 90%;
  background-color: rgb(200,200,200);
  opacity: 0.35;
  cursor: pointer;
}

div.initial_prompt p.help {
  text-align: center;
}

div.initial_prompt p.close {
  text-align: right;
  font-style: italic;
}

div.slidy_toc {
  position: absolute;
  z-index: 300;
  width: 60%;
  max-width: 30em;
  height: 30em;
  overflow: auto;
  top: auto;
  right: auto;
  left: 4em;
  bottom: 4em;
  padding: 1em;
  background: rgb(240,240,240);
  border-style: solid;
  border-width: 2px;
  font-size: 60%;
}

div.slidy_toc .toc_heading {
  text-align: center;
  width: 100%;
  margin: 0;
  margin-bottom: 1em;
  border-bottom-style: solid;
  border-bottom-color: rgb(180,180,180);
  border-bottom-width: 1px;
}

div.slide {
  z-index: 20;
  margin: 0 0 0 0;
  padding-top: 0;
  padding-bottom: 0;
  padding-left: 20px;
  padding-right: 20px;
  border-width: 0;
  clear: both;
  top: 0;
  bottom: 0;
  left: 0;
  right: 0;
  line-height: 120%;
  background-color: transparent;
}

div.background {
  display: none;
}

div.handout {
  margin-left: 20px;
  margin-right: 20px;
}

div.slide.titlepage {
  text-align: center;
}

div.slide.titlepage.h1 {
  padding-top: 10%;
}

div.slide h1 {
  padding-left: 0;
  padding-right: 20pt;
  padding-top: 4pt;
  padding-bottom: 4pt;
  margin-top: 0;
  margin-left: 0;
  margin-right: 60pt;
  margin-bottom: 0.5em;
  display: block;
  font-size: 160%;
  line-height: 1.2em;
  background: transparent;
}

div.toc {
  position: absolute;
  top: auto;
  bottom: 4em;
  left: 4em;
  right: auto;
  width: 60%;
  max-width: 30em;
  height: 30em;
  border: solid thin black;
  padding: 1em;
  background: rgb(240,240,240);
  color: black;
  z-index: 300;
  overflow: auto;
  display: block;
  visibility: visible;
}

div.toc-heading {
  width: 100%;
  border-bottom: solid 1px rgb(180,180,180);
  margin-bottom: 1em;
  text-align: center;
}

/*
pre {
 font-size: 80%;
 font-weight: bold;
 line-height: 120%;
 padding-top: 0.2em;
 padding-bottom: 0.2em;
 padding-left: 1em;
 padding-right: 1em;
 border-style: solid;
 border-left-width: 1em;
 border-top-width: thin;
 border-right-width: thin;
 border-bottom-width: thin;
 border-color: #95ABD0;
 color: #00428C;
 background-color: #E4E5E7;
}
*/

/*
li pre { margin-left: 0; }

blockquote { font-style: italic }

img { background-color: transparent }

p.copyright { font-size: smaller }
*/

.center { text-align: center }
.footnote { font-size: smaller; margin-left: 2em; }

/*
a img { border-width: 0; border-style: none }
*/

a:visited { color: navy }
a:link { color: navy }
a:hover { color: red; text-decoration: underline }
a:active { color: red; text-decoration: underline }

a {text-decoration: none}
.navbar a:link {color: white}
.navbar a:visited {color: yellow}
.navbar a:active {color: red}
.navbar a:hover {color: red}

/*
ul { list-style-type: square; }
ul ul { list-style-type: disc; }
ul ul ul { list-style-type: circle; }
ul ul ul ul { list-style-type: disc; }
li { margin-left: 0.5em; margin-top: 0.5em; }
li li { font-size: 85%; font-style: italic }
li li li { font-size: 85%; font-style: normal }
*/

div dt
{
  margin-left: 0;
  margin-top: 1em;
  margin-bottom: 0.5em;
  font-weight: bold;
}
div dd
{
  margin-left: 2em;
  margin-bottom: 0.5em;
}


/*
p,pre,ul,ol,blockquote,h2,h3,h4,h5,h6,dl,table {
  margin-left: 1em;
  margin-right: 1em;
}
*/

p.subhead { font-weight: bold; margin-top: 2em; }

.smaller { font-size: smaller }
.bigger { font-size: 130% }

/*
td,th { padding: 0.2em }
*/

ul {
  margin: 0.5em 1.5em 0.5em 1.5em;
  padding: 0;
}

ol {
  margin: 0.5em 1.5em 0.5em 1.5em;
  padding: 0;
}

ul { list-style-type: square; }
ul ul { list-style-type: disc; }
ul ul ul { list-style-type: circle; }
ul ul ul ul { list-style-type: disc; }

/*
ul li {
  list-style: square;
  margin: 0.1em 0em 0.6em 0;
  padding: 0 0 0 0;
  line-height: 140%;
}

ol li {
  margin: 0.1em 0em 0.6em 1.5em;
  padding: 0 0 0 0px;
  line-height: 140%;
  list-style-type: decimal;
}

li ul li {
  font-size: 85%;
  font-style: italic;
  list-style-type: disc;
  background: transparent;
  padding: 0 0 0 0;
}
li li ul li {
  font-size: 85%;
  font-style: normal;
  list-style-type: circle;
  background: transparent;
  padding: 0 0 0 0;
}
li li li ul li {
  list-style-type: disc;
  background: transparent;
  padding: 0 0 0 0;
}

li ol li {
  list-style-type: decimal;
}


li li ol li {
  list-style-type: decimal;
}
*/

/*
 setting class="outline" on ol or ul makes it behave as an
 ouline list where blocklevel content in li elements is
 hidden by default and can be expanded or collapsed with
 mouse click. Set class="expand" on li to override default
*/

ol.outline li:hover { cursor: pointer }
ol.outline li.nofold:hover { cursor: default }

ul.outline li:hover { cursor: pointer }
ul.outline li.nofold:hover { cursor: default }

ol.outline { list-style:decimal; }
ol.outline ol { list-style-type:lower-alpha }

ol.outline li.nofold {
  padding: 0 0 0 20px;
  background: transparent url(../graphics/nofold-dim.gif) no-repeat 0px 0.5em;
}
ol.outline li.unfolded {
  padding: 0 0 0 20px;
  background: transparent url(../graphics/fold-dim.gif) no-repeat 0px 0.5em;
}
ol.outline li.folded {
  padding: 0 0 0 20px;
  background: transparent url(../graphics/unfold-dim.gif) no-repeat 0px 0.5em;
}
ol.outline li.unfolded:hover {
  padding: 0 0 0 20px;
  background: transparent url(../graphics/fold.gif) no-repeat 0px 0.5em;
}
ol.outline li.folded:hover {
  padding: 0 0 0 20px;
  background: transparent url(../graphics/unfold.gif) no-repeat 0px 0.5em;
}

ul.outline li.nofold {
  padding: 0 0 0 20px;
  background: transparent url(../graphics/nofold-dim.gif) no-repeat 0px 0.5em;
}
ul.outline li.unfolded {
  padding: 0 0 0 20px;
  background: transparent url(../graphics/fold-dim.gif) no-repeat 0px 0.5em;
}
ul.outline li.folded {
  padding: 0 0 0 20px;
  background: transparent url(../graphics/unfold-dim.gif) no-repeat 0px 0.5em;
}
ul.outline li.unfolded:hover {
  padding: 0 0 0 20px;
  background: transparent url(../graphics/fold.gif) no-repeat 0px 0.5em;
}
ul.outline li.folded:hover {
  padding: 0 0 0 20px;
  background: transparent url(../graphics/unfold.gif) no-repeat 0px 0.5em;
}

/* for slides with class "title" in table of contents */
a.titleslide { font-weight: bold; font-style: italic }

/*
 hide images for work around for save as bug
 where browsers fail to save images used by CSS
*/
img.hidden { display: none; visibility: hidden }
div.initial_prompt { display: none; visibility: hidden }

  div.slide {
     visibility: visible;
     position: inherit;
  }
  div.handout {
     border-top-style: solid;
     border-top-width: thin;
     border-top-color: black;
  }

@media screen {
  .hidden { display: none; visibility: visible }

  div.slide.hidden { display: block; visibility: visible }
  div.handout.hidden { display: block; visibility: visible }
  div.background { display: none; visibility: hidden }
  body.single_slide div.initial_prompt { display: block; visibility: visible }
  body.single_slide div.background { display: block; visibility: visible }
  body.single_slide div.background.hidden { display: none; visibility: hidden }
  body.single_slide .invisible { visibility: hidden }
  body.single_slide .hidden { display: none; visibility: hidden }
  body.single_slide div.slide { position: absolute }
  body.single_slide div.handout { display: none; visibility: hidden }
}

@media print {
  .hidden { display: block; visibility: visible }

/*
  div.slide pre { font-size: 60%; padding-left: 0.5em; }
*/
  div.toolbar { display: none; visibility: hidden; }
  div.slidy_toc { display: none; visibility: hidden; }
  div.background { display: none; visibility: hidden; }
  div.slide { page-break-before: always }
  /* :first-child isn't reliable for print media */
  div.slide.first-slide { page-break-before: avoid }
}


/* SJR: AsciiDoc slidy backend tweaks */

ol, ul {
  margin: 0.8em 1.5em 0.8em 1.8em;
}
li > ul, li > ol {
  margin-top: 0.5em;
}

.outline > li.folded,
.outline > li.unfolded {
  color: #527bbd;
}
ul > li{ color: #aaa; }
ul > li > *, ol > li > * { color: black; }

li {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

/* jmi hack */
@media screen {
  body.single_slide .invisible { opacity: 0.15; visibility: visible; }
  /*img.invisible { opacity: 0.1; visibility: visible; } */
  img.invisible { visibility: hidden !important }
}
a {text-decoration: underline;}
</style>
<style type="text/css" title="slidy_color_set_none">
/* empty color set styles */
</style>
<style type="text/css" title="slidy_color_set_yellow">
/* rainbow color styles */
body { background-color: #ffffaa;}
a:link, a:visited, a:hover, a:active { color: blue; text-decoration: underline }
a:hover { color: red; text-decoration: underline }
div.slide { color: black;}
div.slide h1,h2,h3,h4,h5,h6 { color: orange;}
em { color: green;}
tt { color: green;}
div.sidebarblock, div.literalblock, div.listingblock, div.exampleblock, div.title { color: red;}
div.quoteblock, div.verseblock {  color: black; }
div.admonitionblock { color: red;}
</style>
<style type="text/css" title="slidy_color_set_green">
/* blue color styles */
body { background-color: #449900;}
a:link, a:visited, a:hover, a:active { color: fuchsia; text-decoration: underline }
a:hover { color: red; text-decoration: underline }
div.slide { color: yellow;}
div.slide h1,h2,h3,h4,h5,h6 { color: lime;}
em { color: orange;}
tt { color: orange;}
div.sidebarblock, div.literalblock, div.listingblock, div.exampleblock, div.title { color: #44ff00;}
div.quoteblock, div.verseblock {  color: black; }
div.admonitionblock { color: #88ff55;}
</style>
<style type="text/css" title="slidy_color_set_blue">
/* blue color styles */
body { background-color: navy;}
a:link, a:visited, a:hover, a:active { color: yellow; text-decoration: underline }
a:hover { color: red; text-decoration: underline }
div.slide { background-color: navy; color: aqua;}
div.slide h1,h2,h3,h4,h5,h6 { color: aqua;}
em { color: blue;}
tt { color: blue;}
div.sidebarblock, div.literalblock, div.listingblock, div.exampleblock, div.title { color: teal;}
div.admonitionblock { color: teal;}
</style>
<style type="text/css" title="slidy_color_set_black">
/* black color set styles */
body { background-color: black !important; }
a:link, a:visited, a:hover, a:active { color: gray; text-decoration: underline }
a:hover { color: red; text-decoration: underline }
div.slide { color: silver !important; }
span, caption, th { color: silver !important; }
div.slide h1,h2,h3,h4,h5,h6 { color: white;}
em, strong { color: #999999;}
tt { color: blue;}
div.sidebarblock, div.literalblock, div.listingblock, div.exampleblock, div.title { color: black; }
div.admonitionblock, div.quoteblock, div.verseblock {  color: white; }
div.cover.slide, div.cover.slide h1 { background-color: black; }
</style>
<script type="text/javascript">
/*<![CDATA[*/
/* slidy.js

   Copyright (c) 2005-2010 W3C (MIT, ERCIM, Keio), All Rights Reserved.
   W3C liability, trademark, document use and software licensing
   rules apply, see:

   http://www.w3.org/Consortium/Legal/copyright-documents
   http://www.w3.org/Consortium/Legal/copyright-software

   Defines single name "w3c_slidy" in global namespace
   Adds event handlers without trampling on any others

   JMI: Dynamic features added
*/

// the slidy object implementation
var w3c_slidy = {
  // classify which kind of browser we're running under
  ns_pos: (typeof window.pageYOffset!='undefined'),
  khtml: ((navigator.userAgent).indexOf("KHTML") >= 0 ? true : false),
  opera: ((navigator.userAgent).indexOf("Opera") >= 0 ? true : false),
  ipad: ((navigator.userAgent).indexOf("iPad") >= 0 ? true : false),
  iphone: ((navigator.userAgent).indexOf("iPhone") >= 0 ? true : false),
  ie: (typeof document.all != "undefined" && !this.opera),
  ie6: (!this.ns_pos && navigator.userAgent.indexOf("MSIE 6") != -1),
  ie7: (!this.ns_pos && navigator.userAgent.indexOf("MSIE 7") != -1),
  ie8: (!this.ns_pos && navigator.userAgent.indexOf("MSIE 8") != -1),
  ie9: (!this.ns_pos && navigator.userAgent.indexOf("MSIE 9") != -1),
  keyboardless: (this.ipad || this.iphone),

  // are we running as XHTML? (doesn't work on Opera)
  is_xhtml: /xml/.test(document.contentType),

  slide_number: 0, // integer slide count: 0, 1, 2, ...
  slide_number_element: null, // element containing slide number
  slides: [], // set to array of slide div's
  notes: [], // set to array of handout div's
  backgrounds: [], // set to array of background div's
  toolbar: null, // element containing toolbar
  title: null, // document title
  last_shown: null, // last incrementally shown item
  eos: null,  // span element for end of slide indicator
  toc: null, // table of contents
  outline: null, // outline element with the focus
  selected_text_len: 0, // length of drag selection on document
  view_all: 0,  // 1 to view all slides + handouts
  want_toolbar: true,  // user preference to show/hide toolbar
  mouse_click_enabled: true, // enables left click for next slide
  scroll_hack: 0, // IE work around for position: fixed
  disable_slide_click: false,  // used by clicked anchors

  lang: "en", // updated to language specified by html file

  help_anchor: null, // used for keyboard focus hack in showToolbar()
  help_page: "http://www.w3.org/Talks/Tools/Slidy2/help/help.html",
  help_text: "Navigate with mouse click, space bar, Cursor Left/Right, " +
             "or Pg Up and Pg Dn. Use S and B to change font size.",
// jmi
  help_keymap:
    "PGDN\t: nextSlide\n" +
     "PGUP\t: previousSlide\n" +
     "HOME\t: firstSlide\n" +
     "END  \t: lastSlide\n" +
     "SPACE\t: nextContent\n" +
     "->  \t: nextContent\n" +
     "<-  \t: previousContent\n" +
     "A   \t: toggleAllSlides\n" +
     "F   \t: toggleFooter\n" +
     "K   \t: toggleMouseClick\n" +
     "I   \t: toggleIncremental\n" +
     "L   \t: toggleColorSet\n" +
     "T, C\t: tableOfContents\n" +
     "B   \t: biggerFontSize\n" +
     "S   \t: smallerFontSize\n" +
     "M   \t: key mapping\n",

  size_index: 0,
  size_adjustment: 0,
  sizes:  new Array("10pt", "12pt", "14pt", "16pt", "18pt", "20pt",
                    "22pt", "24pt", "26pt", "28pt", "30pt", "32pt"),

  // needed for efficient resizing
  last_width: 0,
  last_height: 0,


  // Needed for cross browser support for relative width/height on
  // object elements. The work around is to save width/height attributes
  // and then to recompute absolute width/height dimensions on resizing
   objects: [],

//jmi
incremental_display: true,

  // attach initialiation event handlers
  set_up: function () {
    var init = function() { w3c_slidy.init(); };
    if (typeof window.addEventListener != "undefined")
      window.addEventListener("load", init, false);
    else
      window.attachEvent("onload", init);
  },

  hide_slides: function () {
    if (document.body && !w3c_slidy.initialized)
      document.body.style.visibility = "hidden";
    else
      setTimeout(w3c_slidy.hide_slides, 50);
  },

  // hack to persuade IE to compute correct document height
  // as needed for simulating fixed positioning of toolbar
  ie_hack: function () {
    window.resizeBy(0,-1);
    window.resizeBy(0, 1);
  },

  init: function () {
    //alert("slidy starting test 10");
    document.body.style.visibility = "visible";
    this.init_localization();
    this.add_toolbar();
    this.wrap_implicit_slides();
    this.collect_slides();
    this.collect_notes();
    this.collect_backgrounds();
    this.objects = document.body.getElementsByTagName("object");
    this.patch_anchors();
    this.slide_number = this.find_slide_number(location.href);
    window.offscreenbuffering = true;
    this.size_adjustment = this.find_size_adjust();
    this.time_left = this.find_duration();
    this.hide_image_toolbar();  // suppress IE image toolbar popup
    this.init_outliner();  // activate fold/unfold support
    this.title = document.title;
    // jmi
    this.color_sets = new Array();
    this.init_color_sets();

    // work around for opera bug
    this.is_xhtml = (document.body.tagName == "BODY" ? false : true);

    if (this.slides.length > 0)
    {
      var slide = this.slides[this.slide_number];

      if (this.slide_number > 0)
      {
        this.set_visibility_all_incremental("visible");
        this.last_shown = this.previous_incremental_item(null);
        this.set_eos_status(true);
      }
      else
      {
        this.last_shown = null;
        this.set_visibility_all_incremental("hidden");
        this.set_eos_status(!this.next_incremental_item(this.last_shown));
      }

      this.set_location();
      this.add_class(this.slides[0], "first-slide");
      w3c_slidy.show_slide(slide);
    }

    this.toc = this.table_of_contents();

    this.add_initial_prompt();

    // bind event handlers without interfering with custom page scripts
    // Tap events behave too weirdly to support clicks reliably on
    // iPhone and iPad, so exclude these from click handler

    if (!this.keyboardless)
      this.add_listener(document.body, "click", this.mouse_button_click);

    this.add_listener(document, "keydown", this.key_down);
    this.add_listener(document, "keypress", this.key_press);
    this.add_listener(window, "resize", this.resized);
    this.add_listener(window, "scroll", this.scrolled);
    this.add_listener(window, "unload", this.unloaded);

    // this seems to be a debugging hack
    //if (!document.body.onclick)
    //  document.body.onclick = function () { };

    this.single_slide_view();

    //this.set_location();

    this.resized();

    if (this.ie7)
      setTimeout(w3c_slidy.ie_hack, 100);

    this.show_toolbar();

    // for back button detection
    setInterval(function () { w3c_slidy.check_location(); }, 200);
    w3c_slidy.initialized = true;
  },

  // create div element with links to each slide
  table_of_contents: function () {
    var toc = this.create_element("div");
    this.add_class(toc, "slidy_toc hidden");
    //toc.setAttribute("tabindex", "0");

    var heading = this.create_element("div");
    this.add_class(heading, "toc-heading");
    heading.innerHTML = this.localize("Table of Contents");

    toc.appendChild(heading);
    var previous = null;

    for (var i = 0; i < this.slides.length; ++i)
    {
      var title = this.has_class(this.slides[i], "title");
      var num = document.createTextNode((i + 1) + ". ");

      toc.appendChild(num);

      var a = this.create_element("a");
      a.setAttribute("href", "#(" + (i+1) + ")");

      if (title)
        this.add_class(a, "titleslide");

      var name = document.createTextNode(this.slide_name(i));
      a.appendChild(name);
      a.onclick = w3c_slidy.toc_click;
      a.onkeydown = w3c_slidy.toc_key_down;
      a.previous = previous;

      if (previous)
        previous.next = a;

      toc.appendChild(a);

      if (i == 0)
        toc.first = a;

      if (i < this.slides.length - 1)
      {
        var br = this.create_element("br");
        toc.appendChild(br);
      }

      previous = a;
    }

    toc.focus = function () {
      if (this.first)
        this.first.focus();
    }

    toc.onmouseup = w3c_slidy.mouse_button_up;

    toc.onclick = function (e) {
      e||(e=window.event);

      if (w3c_slidy.selected_text_len <= 0)
         w3c_slidy.hide_table_of_contents(true);

      w3c_slidy.stop_propagation(e);

      if (e.cancel != undefined)
        e.cancel = true;

      if (e.returnValue != undefined)
        e.returnValue = false;

      return false;
    };

    document.body.insertBefore(toc, document.body.firstChild);
    return toc;
  },

  is_shown_toc: function () {
    return !w3c_slidy.has_class(w3c_slidy.toc, "hidden");
  },

  show_table_of_contents: function () {
    w3c_slidy.remove_class(w3c_slidy.toc, "hidden");
    var toc = w3c_slidy.toc;
    toc.focus();

    if (w3c_slidy.ie7 && w3c_slidy.slide_number == 0)
      setTimeout(w3c_slidy.ie_hack, 100);
  },

  hide_table_of_contents: function (focus) {
    w3c_slidy.add_class(w3c_slidy.toc, "hidden");

    if (focus && !w3c_slidy.opera)
      w3c_slidy.help_anchor.focus();
  },

  toggle_table_of_contents: function () {
    if (w3c_slidy.is_shown_toc())
      w3c_slidy.hide_table_of_contents(true);
    else
      w3c_slidy.show_table_of_contents();
  },

  // called on clicking toc entry
  toc_click: function (e) {
    if (!e)
      e = window.event;

    var target = w3c_slidy.get_target(e);

    if (target && target.nodeType == 1)
    {
      var uri = target.getAttribute("href");

      if (uri)
      {
        //alert("going to " + uri);
        var slide = w3c_slidy.slides[w3c_slidy.slide_number];
        w3c_slidy.hide_slide(slide);
        w3c_slidy.slide_number = w3c_slidy.find_slide_number(uri);
        slide = w3c_slidy.slides[w3c_slidy.slide_number];
        w3c_slidy.last_shown = null;
        w3c_slidy.set_location();
        w3c_slidy.set_visibility_all_incremental("hidden");
        w3c_slidy.set_eos_status(!w3c_slidy.next_incremental_item(w3c_slidy.last_shown));
        w3c_slidy.show_slide(slide);
        //target.focus();

        try
        {
          if (!w3c_slidy.opera)
            w3c_slidy.help_anchor.focus();
        }
        catch (e)
        {
        }
      }
    }

    w3c_slidy.hide_table_of_contents(true);
    if (w3c_slidy.ie7) w3c_slidy.ie_hack();
    w3c_slidy.stop_propagation(e);
    return w3c_slidy.cancel(e);
  },

  // called onkeydown for toc entry
  toc_key_down: function (event) {
    var key;

    if (!event)
      var event = window.event;

    // kludge around NS/IE differences
    if (window.event)
      key = window.event.keyCode;
    else if (event.which)
      key = event.which;
    else
      return true; // Yikes! unknown browser

    // ignore event if key value is zero
    // as for alt on Opera and Konqueror
    if (!key)
      return true;

    // check for concurrent control/command/alt key
    // but are these only present on mouse events?

    if (event.ctrlKey || event.altKey)
      return true;

    if (key == 13)
    {
      var uri = this.getAttribute("href");

      if (uri)
      {
        //alert("going to " + uri);
       var slide = w3c_slidy.slides[w3c_slidy.slide_number];
        w3c_slidy.hide_slide(slide);
        w3c_slidy.slide_number = w3c_slidy.find_slide_number(uri);
        slide = w3c_slidy.slides[w3c_slidy.slide_number];
        w3c_slidy.last_shown = null;
        w3c_slidy.set_location();
        w3c_slidy.set_visibility_all_incremental("hidden");
        w3c_slidy.set_eos_status(!w3c_slidy.next_incremental_item(w3c_slidy.last_shown));
        w3c_slidy.show_slide(slide);
        //target.focus();

        try
        {
          if (!w3c_slidy.opera)
            w3c_slidy.help_anchor.focus();
        }
        catch (e)
        {
        }
      }

      w3c_slidy.hide_table_of_contents(true);

      if (self.ie7)
       w3c_slidy.ie_hack();

      return w3c_slidy.cancel(event);
    }

    if (key == 40 && this.next)
    {
      this.next.focus();
      return w3c_slidy.cancel(event);
    }

    if (key == 38 && this.previous)
    {
      this.previous.focus();
      return w3c_slidy.cancel(event);
    }

    return true;
  },


  // ### OBSOLETE ###
  before_print: function () {
    this.show_all_slides();
    this.hide_toolbar();
    alert("before print");
  },

  // ### OBSOLETE ###
  after_print: function () {
    if (!this.view_all)
    {
      this.single_slide_view();
      this.show_toolbar();
    }
    alert("after print");
  },

  // ### OBSOLETE ###
  print_slides: function () {
    this.before_print();
    window.print();
    this.after_print();
  },

  // ### OBSOLETE ?? ###
  toggle_view: function () {
    if (this.view_all)
    {
      this.single_slide_view();
      this.show_toolbar();
      this.view_all = 0;
    }
    else
    {
      this.show_all_slides();
      this.hide_toolbar();
      this.view_all = 1;
    }
  },

  // prepare for printing  ### OBSOLETE ###
  show_all_slides: function () {
    this.remove_class(document.body, "single_slide");
    this.set_visibility_all_incremental("visible");
  },

  // restore after printing  ### OBSOLETE ###
  single_slide_view: function () {
    this.add_class(document.body, "single_slide");
    this.set_visibility_all_incremental("visible");
    this.last_shown = this.previous_incremental_item(null);
  },

  // suppress IE's image toolbar pop up
  hide_image_toolbar: function () {
    if (!this.ns_pos)
    {
      var images = document.getElementsByTagName("IMG");

      for (var i = 0; i < images.length; ++i)
        images[i].setAttribute("galleryimg", "no");
    }
  },

  unloaded: function (e) {
    //alert("unloaded");
  },

  // Safari and Konqueror don't yet support getComputedStyle()
  // and they always reload page when location.href is updated
  is_KHTML: function () {
    var agent = navigator.userAgent;
    return (agent.indexOf("KHTML") >= 0 ? true : false);
  },

  // find slide name from first h1 element
  // default to document title + slide number
  slide_name: function (index) {
    var name = null;
    var slide = this.slides[index];

    var heading = this.find_heading(slide);

    if (heading)
      name = this.extract_text(heading);

    if (!name)
      name = this.title + "(" + (index + 1) + ")";

    name.replace(/\&/g, "&amp;");
    name.replace(/\</g, "&lt;");
    name.replace(/\>/g, "&gt;");

    return name;
  },

  // find first h1 element in DOM tree
  find_heading: function (node) {
    if (!node || node.nodeType != 1)
      return null;

    if (node.nodeName == "H1" || node.nodeName == "h1")
      return node;

    var child = node.firstChild;

    while (child)
    {
      node = this.find_heading(child);

      if (node)
        return node;

      child = child.nextSibling;
    }

    return null;
  },

  // recursively extract text from DOM tree
  extract_text: function (node) {
    if (!node)
      return "";

    // text nodes
    if (node.nodeType == 3)
      return node.nodeValue;

    // elements
    if (node.nodeType == 1)
    {
      node = node.firstChild;
      var text = "";

      while (node)
      {
        text = text + this.extract_text(node);
        node = node.nextSibling;
      }

      return text;
    }

    return "";
  },

  // find copyright text from meta element
  find_copyright: function () {
    var name, content;
    var meta = document.getElementsByTagName("meta");

    for (var i = 0; i < meta.length; ++i)
    {
      name = meta[i].getAttribute("name");
      content = meta[i].getAttribute("content");

      if (name == "copyright")
        return content;
    }

    return null;
  },

  find_size_adjust: function () {
    var name, content, offset;
    var meta = document.getElementsByTagName("meta");

    for (var i = 0; i < meta.length; ++i)
    {
      name = meta[i].getAttribute("name");
      content = meta[i].getAttribute("content");

      if (name == "font-size-adjustment")
        return 1 * content;
    }

    return 1;
  },

  // <meta name="duration" content="20" />  for 20 minutes
  find_duration: function () {
    var name, content, offset;
    var meta = document.getElementsByTagName("meta");

    for (var i = 0; i < meta.length; ++i)
    {
      name = meta[i].getAttribute("name");
      content = meta[i].getAttribute("content");

      if (name == "duration")
        return 60000 * content;
    }

    return null;
  },

  replace_by_non_breaking_space: function (str) {
    for (var i = 0; i < str.length; ++i)
      str[i] = 160;
  },

  // ### CHECK ME ### is use of "li" okay for text/html?
  // for XHTML do we also need to specify namespace?
  init_outliner: function () {
    var items = document.getElementsByTagName("li");

    for (var i = 0; i < items.length; ++i)
    {
      var target = items[i];

      if (!this.has_class(target.parentNode, "outline"))
        continue;

      target.onclick = this.outline_click;
/* ### more work needed for IE6
      if (!this.ns_pos)
      {
        target.onmouseover = this.hover_outline;
        target.onmouseout = this.unhover_outline;
      }
*/
      if (this.foldable(target))
      {
        target.foldable = true;
        target.onfocus = function () {w3c_slidy.outline = this;};
        target.onblur = function () {w3c_slidy.outline = null;};

        if (!target.getAttribute("tabindex"))
          target.setAttribute("tabindex", "0");

        if (this.has_class(target, "expand"))
          this.unfold(target);
        else
          this.fold(target);
      }
      else
      {
        this.add_class(target, "nofold");
        target.visible = true;
        target.foldable = false;
      }
    }
  },

  foldable: function (item) {
    if (!item || item.nodeType != 1)
      return false;

    var node = item.firstChild;

    while (node)
    {
      if (node.nodeType == 1 && this.is_block(node))
        return true;

      node = node.nextSibling;
    }

    return false;
  },

  // ### CHECK ME ### switch to add/remove "hidden" class
  fold: function (item) {
    if (item)
    {
      this.remove_class(item, "unfolded");
      this.add_class(item, "folded");
    }

    var node = item ? item.firstChild : null;

    while (node)
    {
      if (node.nodeType == 1 && this.is_block(node)) // element
      {
         w3c_slidy.add_class(node, "hidden");
      }

      node = node.nextSibling;
    }

    item.visible = false;
  },

  // ### CHECK ME ### switch to add/remove "hidden" class
  unfold: function (item) {
    if (item)
    {
      this.add_class(item, "unfolded");
      this.remove_class(item, "folded");
    }

    var node = item ? item.firstChild : null;

    while (node)
    {
      if (node.nodeType == 1 && this.is_block(node)) // element
      {
        w3c_slidy.remove_class(node, "hidden");
      }

      node = node.nextSibling;
    }

    item.visible = true;
  },

  outline_click: function (e) {
    if (!e)
      e = window.event;

    var rightclick = false;
    var target = w3c_slidy.get_target(e);

    while (target && target.visible == undefined)
      target = target.parentNode;

    if (!target)
      return true;

    if (e.which)
      rightclick = (e.which == 3);
    else if (e.button)
      rightclick = (e.button == 2);

    if (!rightclick && target.visible != undefined)
    {
      if (target.foldable)
      {
        if (target.visible)
          w3c_slidy.fold(target);
        else
          w3c_slidy.unfold(target);
      }

      w3c_slidy.stop_propagation(e);
      e.cancel = true;
      e.returnValue = false;
    }

    return false;
  },

  add_initial_prompt: function () {
    var prompt = this.create_element("div");
    prompt.setAttribute("class", "initial_prompt");

    var p1 = this.create_element("p");
    prompt.appendChild(p1);
    p1.setAttribute("class", "help");

    if (this.keyboardless)
      p1.innerHTML = "Tap footer to move to next slide";
    else
      p1.innerHTML = "Space or Right Arrow to move to next " +
                     "slide, M to see keys mapping, click help below for more details";

    this.add_listener(prompt, "click", function (e) {
      document.body.removeChild(prompt);
      w3c_slidy.stop_propagation(e);

      if (e.cancel != undefined)
        e.cancel = true;

      if (e.returnValue != undefined)
        e.returnValue = false;

      return false;
    });

    document.body.appendChild(prompt);
    this.initial_prompt = prompt;
    setTimeout(function() {document.body.removeChild(prompt);}, 5000);
  },

  add_toolbar: function () {
    var counter, page;

     this.toolbar = this.create_element("div");
     this.toolbar.setAttribute("class", "toolbar");

     // a reasonably behaved browser
     if (this.ns_pos || !this.ie6)
     {
       var right = this.create_element("div");
       right.setAttribute("style", "float: right; text-align: right");

       counter = this.create_element("span")
       counter.innerHTML = this.localize("slide") + " n/m";
       right.appendChild(counter);
       this.toolbar.appendChild(right);

       var left = this.create_element("div");
       left.setAttribute("style", "text-align: left");

       // global end of slide indicator
       this.eos = this.create_element("span");
       this.eos.innerHTML = "* ";
       left.appendChild(this.eos);

       var help = this.create_element("a");
       help.setAttribute("href", this.help_page);
       help.setAttribute("title", this.localize(this.help_text));
       help.innerHTML = this.localize("help?");
       left.appendChild(help);
       this.help_anchor = help;  // save for focus hack

       var gap1 = document.createTextNode(" ");
       left.appendChild(gap1);

       var contents = this.create_element("a");
       contents.setAttribute("href", "javascript:w3c_slidy.toggle_table_of_contents()");
       contents.setAttribute("title", this.localize("table of contents"));
       contents.innerHTML = this.localize("contents?");
       left.appendChild(contents);

       var gap2 = document.createTextNode(" ");
       left.appendChild(gap2);

       var copyright = this.find_copyright();

       if (copyright)
       {
         var span = this.create_element("span");
         span.className = "copyright";
         span.innerHTML = copyright;
         left.appendChild(span);
       }

       this.toolbar.setAttribute("tabindex", "0");
       this.toolbar.appendChild(left);
     }
     else // IE6 so need to work around its poor CSS support
     {
       this.toolbar.style.position = (this.ie7 ? "fixed" : "absolute");
       this.toolbar.style.zIndex = "200";
       this.toolbar.style.width = "99.9%";
       this.toolbar.style.height = "1.2em";
       this.toolbar.style.top = "auto";
       this.toolbar.style.bottom = "0";
       this.toolbar.style.left = "0";
       this.toolbar.style.right = "0";
       this.toolbar.style.textAlign = "left";
       this.toolbar.style.fontSize = "60%";
       this.toolbar.style.color = "red";
       this.toolbar.borderWidth = 0;
       this.toolbar.className = "toolbar";
       this.toolbar.style.background = "rgb(240,240,240)";

       // would like to have help text left aligned
       // and page counter right aligned, floating
       // div's don't work, so instead use nested
       // absolutely positioned div's.

       var sp = this.create_element("span");
       sp.innerHTML = "&nbsp;&nbsp;*&nbsp;";
       this.toolbar.appendChild(sp);
       this.eos = sp;  // end of slide indicator

       var help = this.create_element("a");
       help.setAttribute("href", this.help_page);
       help.setAttribute("title", this.localize(this.help_text));
       help.innerHTML = this.localize("help?");
       this.toolbar.appendChild(help);
       this.help_anchor = help;  // save for focus hack

       var gap1 = document.createTextNode(" ");
       this.toolbar.appendChild(gap1);

       var contents = this.create_element("a");
       contents.setAttribute("href", "javascript:toggleTableOfContents()");
       contents.setAttribute("title", this.localize("table of contents".localize));
       contents.innerHTML = this.localize("contents?");
       this.toolbar.appendChild(contents);

       var gap2 = document.createTextNode(" ");
       this.toolbar.appendChild(gap2);

       var copyright = this.find_copyright();

       if (copyright)
       {
         var span = this.create_element("span");
         span.innerHTML = copyright;
         span.style.color = "black";
         span.style.marginLeft = "0.5em";
         this.toolbar.appendChild(span);
       }

       counter = this.create_element("div")
       counter.style.position = "absolute";
       counter.style.width = "auto"; //"20%";
       counter.style.height = "1.2em";
       counter.style.top = "auto";
       counter.style.bottom = 0;
       counter.style.right = "0";
       counter.style.textAlign = "right";
       counter.style.color = "red";
       counter.style.background = "rgb(240,240,240)";

       counter.innerHTML = this.localize("slide") + " n/m";
       this.toolbar.appendChild(counter);
     }

     // ensure that click isn't passed through to the page
     this.toolbar.onclick =
         function (e) {
           if (!e)
             e = window.event;

           var target = e.target;

           if (!target && e.srcElement)
             target = e.srcElement;

           // work around Safari bug
           if (target && target.nodeType == 3)
             target = target.parentNode;

           w3c_slidy.stop_propagation(e);

           if (target && target.nodeName.toLowerCase() != "a")
             w3c_slidy.mouse_button_click(e);
         };

     this.slide_number_element = counter;
     this.set_eos_status(false);
     document.body.appendChild(this.toolbar);
  },

  // wysiwyg editors make it hard to use div elements
  // e.g. amaya loses the div when you copy and paste
  // this function wraps div elements around implicit
  // slides which start with an h1 element and continue
  // up to the next heading or div element
  wrap_implicit_slides: function () {
    var i, heading, node, next, div;
    var headings = document.getElementsByTagName("h1");

    if (!headings)
      return;

    for (i = 0; i < headings.length; ++i)
    {
      heading = headings[i];

      if (heading.parentNode != document.body)
        continue;

      node = heading.nextSibling;

      div = document.createElement("div");
      this.add_class(div, "slide");
      document.body.replaceChild(div, heading);
      div.appendChild(heading);

      while (node)
      {
        if (node.nodeType == 1 &&    // an element
             (node.nodeName == "H1" ||
              node.nodeName == "h1" ||
              node.nodeName == "DIV" ||
              node.nodeName == "div"))
          break;

        next = node.nextSibling;
        node = document.body.removeChild(node);
        div.appendChild(node);
        node = next;
      }
    }
  },

// return new array of all slides
  collect_slides: function () {
    var slides = new Array();
    var divs = document.body.getElementsByTagName("div");

    for (var i = 0; i < divs.length; ++i)
    {
      div = divs.item(i);

      if (this.has_class(div, "slide"))
      {
        // add slide to collection
        slides[slides.length] = div;

        // hide each slide as it is found
        this.add_class(div, "hidden");

        // add dummy <br/> at end for scrolling hack
        var node1 = document.createElement("br");
        div.appendChild(node1);
        var node2 = document.createElement("br");
        div.appendChild(node2);
      }
      else if (this.has_class(div, "background"))
      {  // work around for Firefox SVG reload bug
        // which otherwise replaces 1st SVG graphic with 2nd
        div.style.display = "block";
      }
    }

    this.slides = slides;
  },

  // return new array of all <div class="handout">
  collect_notes: function () {
    var notes = new Array();
    var divs = document.body.getElementsByTagName("div");

    for (var i = 0; i < divs.length; ++i)
    {
      div = divs.item(i);

      if (this.has_class(div, "handout"))
      {
        // add note to collection
        notes[notes.length] = div;

        // and hide it
        this.add_class(div, "hidden");
      }
    }

    this.notes = notes;
  },

  // return new array of all <div class="background">
  // including named backgrounds e.g. class="background titlepage"
  collect_backgrounds: function () {
    var backgrounds = new Array();
    var divs = document.body.getElementsByTagName("div");

    for (var i = 0; i < divs.length; ++i)
    {
      div = divs.item(i);

      if (this.has_class(div, "background"))
      {
        // add background to collection
        backgrounds[backgrounds.length] = div;

        // and hide it
        this.add_class(div, "hidden");
      }
    }

    this.backgrounds = backgrounds;
  },

  // set click handlers on all anchors
  patch_anchors: function () {
    var self = w3c_slidy;
    var handler = function (event) {
      // compare this.href with location.href
      // for link to another slide in this doc

      if (self.page_address(this.href) == self.page_address(location.href))
      {
        // yes, so find new slide number
        var newslidenum = self.find_slide_number(this.href);

        if (newslidenum != self.slide_number)
        {
          var slide = self.slides[self.slide_number];
          self.hide_slide(slide);
          self.slide_number = newslidenum;
          slide = self.slides[self.slide_number];
          self.show_slide(slide);
          self.set_location();
        }
      }
      else
        w3c_slidy.stop_propagation(event);

//      else if (this.target == null)
//        location.href = this.href;

      this.blur();
      self.disable_slide_click = true;
    };

    var anchors = document.body.getElementsByTagName("a");

    for (var i = 0; i < anchors.length; ++i)
    {
      if (window.addEventListener)
        anchors[i].addEventListener("click", handler, false);
      else
        anchors[i].attachEvent("onclick", handler);
    }
  },

  // ### CHECK ME ### see which functions are invoked via setTimeout
  // either directly or indirectly for use of w3c_slidy vs this
  show_slide_number: function () {
    var timer = w3c_slidy.get_timer();
    w3c_slidy.slide_number_element.innerHTML = timer + w3c_slidy.localize("slide") + " " +
           (w3c_slidy.slide_number + 1) + "/" + w3c_slidy.slides.length;
  },

  // every 200mS check if the location has been changed as a
  // result of the user activating the Back button/menu item
  // doesn't work for Opera < 9.5
  check_location: function () {
    var hash = location.hash;

    if (w3c_slidy.slide_number > 0 && (hash == "" || hash == "#"))
      w3c_slidy.goto_slide(0);
    else if (hash.length > 2 && hash != "#("+(w3c_slidy.slide_number+1)+")")
    {
      var num = parseInt(location.hash.substr(2));

      if (!isNaN(num))
        w3c_slidy.goto_slide(num-1);
    }

    if (w3c_slidy.time_left && w3c_slidy.slide_number > 0)
    {
      w3c_slidy.show_slide_number();

      if (w3c_slidy.time_left > 0)
        w3c_slidy.time_left -= 200;
    }
  },

  get_timer: function () {
    var timer = "";
    if (w3c_slidy.time_left)
    {
      var mins, secs;
      secs = Math.floor(w3c_slidy.time_left/1000);
      mins = Math.floor(secs / 60);
      secs = secs % 60;
      timer = (mins ? mins+"m" : "") + secs + "s ";
    }

    return timer;
  },

  // this doesn't push location onto history stack for IE
  // for which a hidden iframe hack is needed: load page into
  // the iframe with script that set's parent's location.hash
  // but that won't work for standalone use unless we can
  // create the page dynamically via a javascript: URL
  set_location: function () {
     var uri = w3c_slidy.page_address(location.href);
     var hash = "#(" + (w3c_slidy.slide_number+1) + ")";

     if (w3c_slidy.slide_number >= 0)
       uri = uri + hash;

     if (w3c_slidy.ie && !w3c_slidy.ie8)
       w3c_slidy.push_hash(hash);

     if (uri != location.href) // && !khtml
        location.href = uri;

     if (this.khtml)
        hash = "(" + (w3c_slidy.slide_number+1) + ")";

     if (!this.ie && location.hash != hash && location.hash != "")
       location.hash = hash;

     document.title = w3c_slidy.title + " (" + (w3c_slidy.slide_number+1) + ")";
     w3c_slidy.show_slide_number();
  },

  page_address: function (uri) {
    var i = uri.indexOf("#");

    if (i < 0)
      i = uri.indexOf("%23");

    // check if anchor is entire page

    if (i < 0)
      return uri;  // yes

    return uri.substr(0, i);
  },

  // only used for IE6 and IE7
  on_frame_loaded: function (hash) {
    location.hash = hash;
    var uri = w3c_slidy.page_address(location.href);
    location.href = uri + hash;
  },

  // history hack with thanks to Bertrand Le Roy
  push_hash: function (hash) {
    if (hash == "") hash = "#(1)";
      window.location.hash = hash;

    var doc = document.getElementById("historyFrame").contentWindow.document;
  },

  // find current slide based upon location
  // first find target anchor and then look
  // for associated div element enclosing it
  // finally map that to slide number
  find_slide_number: function (uri) {
    // first get anchor from page location

    var i = uri.indexOf("#");

    // check if anchor is entire page
    if (i < 0)
      return 0;  // yes

    var anchor = unescape(uri.substr(i+1));

    // now use anchor as XML ID to find target
    var target = document.getElementById(anchor);

    if (!target)
    {
      // does anchor look like "(2)" for slide 2 ??
      // where first slide is (1)
      var re = /\((\d)+\)/;

      if (anchor.match(re))
      {
        var num = parseInt(anchor.substring(1, anchor.length-1));

        if (num > this.slides.length)
          num = 1;

        if (--num < 0)
          num = 0;

        return num;
      }

      // accept [2] for backwards compatibility
      re = /\[(\d)+\]/;

      if (anchor.match(re))
      {
         var num = parseInt(anchor.substring(1, anchor.length-1));

         if (num > this.slides.length)
            num = 1;

         if (--num < 0)
            num = 0;

         return num;
      }

      // oh dear unknown anchor
      return 0;
    }

    // search for enclosing slide

    while (true)
    {
      // browser coerces html elements to uppercase!
      if (target.nodeName.toLowerCase() == "div" &&
            this.has_class(target, "slide"))
      {
        // found the slide element
        break;
      }

      // otherwise try parent element if any

      target = target.parentNode;

      if (!target)
      {
        return 0;   // no luck!
      }
    };

    for (i = 0; i < slides.length; ++i)
    {
      if (slides[i] == target)
        return i;  // success
    }

    // oh dear still no luck
    return 0;
  },

  previous_slide: function (incremental) {
    if (!w3c_slidy.view_all)
    {
      var slide;

//jmi
if (!w3c_slidy.incremental_display) {incremental = false;}

      if ((incremental || w3c_slidy.slide_number == 0) && w3c_slidy.last_shown != null)
      {
        w3c_slidy.last_shown = w3c_slidy.hide_previous_item(w3c_slidy.last_shown);
        w3c_slidy.set_eos_status(false);
      }
      else if (w3c_slidy.slide_number > 0)
      {
        slide = w3c_slidy.slides[w3c_slidy.slide_number];
        w3c_slidy.hide_slide(slide);

        w3c_slidy.slide_number = w3c_slidy.slide_number - 1;
        slide = w3c_slidy.slides[w3c_slidy.slide_number];
        w3c_slidy.set_visibility_all_incremental("visible");
        w3c_slidy.last_shown = w3c_slidy.previous_incremental_item(null);
        w3c_slidy.set_eos_status(true);
        w3c_slidy.show_slide(slide);
      }

      w3c_slidy.set_location();

      if (!w3c_slidy.ns_pos)
        w3c_slidy.refresh_toolbar(200);
    }
  },

  next_slide: function (incremental) {
    if (!w3c_slidy.view_all)
    {
      var slide, last = w3c_slidy.last_shown;
//jmi
if (!w3c_slidy.incremental_display) {incremental = false;}

      if (incremental || w3c_slidy.slide_number == w3c_slidy.slides.length - 1)
         w3c_slidy.last_shown = w3c_slidy.reveal_next_item(w3c_slidy.last_shown);

      if ((!incremental || w3c_slidy.last_shown == null) &&
             w3c_slidy.slide_number < w3c_slidy.slides.length - 1)
      {
         slide = w3c_slidy.slides[w3c_slidy.slide_number];
         w3c_slidy.hide_slide(slide);

         w3c_slidy.slide_number = w3c_slidy.slide_number + 1;
         slide = w3c_slidy.slides[w3c_slidy.slide_number];
         w3c_slidy.last_shown = null;
         w3c_slidy.set_visibility_all_incremental("hidden");
         w3c_slidy.show_slide(slide);
      }
      else if (!w3c_slidy.last_shown)
      {
         if (last && incremental)
           w3c_slidy.last_shown = last;
      }

      w3c_slidy.set_location();

      w3c_slidy.set_eos_status(!w3c_slidy.next_incremental_item(w3c_slidy.last_shown));

      if (!w3c_slidy.ns_pos)
         w3c_slidy.refresh_toolbar(200);
     }
  },

  // to first slide with nothing revealed
  // i.e. state at start of presentation
  first_slide: function () {
     if (!w3c_slidy.view_all)
     {
       var slide;

       if (w3c_slidy.slide_number != 0)
       {
         slide = w3c_slidy.slides[w3c_slidy.slide_number];
         w3c_slidy.hide_slide(slide);

         w3c_slidy.slide_number = 0;
         slide = w3c_slidy.slides[w3c_slidy.slide_number];
         w3c_slidy.last_shown = null;
         w3c_slidy.set_visibility_all_incremental("hidden");
         w3c_slidy.show_slide(slide);
       }

       w3c_slidy.set_eos_status(
         !w3c_slidy.next_incremental_item(w3c_slidy.last_shown));
       w3c_slidy.set_location();
     }
  },

  // goto last slide with everything revealed
  // i.e. state at end of presentation
  last_slide: function () {
    if (!w3c_slidy.view_all)
    {
      var slide;

      w3c_slidy.last_shown = null; //revealNextItem(lastShown);

      if (w3c_slidy.last_shown == null &&
          w3c_slidy.slide_number < w3c_slidy.slides.length - 1)
      {
         slide = w3c_slidy.slides[w3c_slidy.slide_number];
         w3c_slidy.hide_slide(slide);
         w3c_slidy.slide_number = w3c_slidy.slides.length - 1;
         slide = w3c_slidy.slides[w3c_slidy.slide_number];
         w3c_slidy.set_visibility_all_incremental("visible");
         w3c_slidy.last_shown = w3c_slidy.previous_incremental_item(null);

         w3c_slidy.show_slide(slide);
      }
      else
      {
         w3c_slidy.set_visibility_all_incremental("visible");
         w3c_slidy.last_shown = w3c_slidy.previous_incremental_item(null);
      }

      w3c_slidy.set_eos_status(true);
      w3c_slidy.set_location();
    }
  },


  // ### check this and consider add/remove class
  set_eos_status: function (state) {
    if (this.eos)
      this.eos.style.color = (state ? "rgb(240,240,240)" : "red");
  },

  // first slide is 0
  goto_slide: function (num) {
    //alert("going to slide " + (num+1));
    var slide = w3c_slidy.slides[w3c_slidy.slide_number];
    w3c_slidy.hide_slide(slide);
    w3c_slidy.slide_number = num;
    slide = w3c_slidy.slides[w3c_slidy.slide_number];
    w3c_slidy.last_shown = null;
    w3c_slidy.set_visibility_all_incremental("hidden");
    w3c_slidy.set_eos_status(!w3c_slidy.next_incremental_item(w3c_slidy.last_shown));
    document.title = w3c_slidy.title + " (" + (w3c_slidy.slide_number+1) + ")";
    w3c_slidy.show_slide(slide);
    w3c_slidy.show_slide_number();
  },


  show_slide: function (slide) {
    this.sync_background(slide);
    window.scrollTo(0,0);
    this.remove_class(slide, "hidden");
  },

  hide_slide: function (slide) {
    this.add_class(slide, "hidden");
  },

  // show just the backgrounds pertinent to this slide
  // when slide background-color is transparent
  // this should now work with rgba color values
  sync_background: function (slide) {
    var background;
    var bgColor;

    if (slide.currentStyle)
      bgColor = slide.currentStyle["backgroundColor"];
    else if (document.defaultView)
    {
      var styles = document.defaultView.getComputedStyle(slide,null);

      if (styles)
        bgColor = styles.getPropertyValue("background-color");
      else // broken implementation probably due Safari or Konqueror
      {
        //alert("defective implementation of getComputedStyle()");
        bgColor = "transparent";
      }
    }
    else
      bgColor == "transparent";

    if (bgColor == "transparent" ||
        bgColor.indexOf("rgba") >= 0 ||
        bgColor.indexOf("opacity") >= 0)
    {
      var slideClass = this.get_class_list(slide);

      for (var i = 0; i < this.backgrounds.length; i++)
      {
        background = this.backgrounds[i];

        var bgClass = this.get_class_list(background);

        if (this.matching_background(slideClass, bgClass))
          this.remove_class(background, "hidden");
        else
          this.add_class(background, "hidden");
      }
    }
    else // forcibly hide all backgrounds
      this.hide_backgrounds();
  },

  hide_backgrounds: function () {
    for (var i = 0; i < this.backgrounds.length; i++)
    {
      background = this.backgrounds[i];
      this.add_class(background, "hidden");
    }
  },

  // compare classes for slide and background
  matching_background: function (slideClass, bgClass) {
    var i, count, pattern, result;

    // define pattern as regular expression
    pattern = /\w+/g;

    // check background class names
    result = bgClass.match(pattern);

    for (i = count = 0; i < result.length; i++)
    {
      if (result[i] == "hidden")
        continue;

      if (result[i] == "background")
	continue;

      ++count;
    }

    if (count == 0)  // default match
      return true;

    // check for matches and place result in array
    result = slideClass.match(pattern);

    // now check if desired name is present for background
    for (i = count = 0; i < result.length; i++)
    {
      if (result[i] == "hidden")
        continue;

      if (this.has_token(bgClass, result[i]))
        return true;
    }

    return false;
  },

  resized: function () {
     var width = 0;

     if ( typeof( window.innerWidth ) == 'number' )
       width = window.innerWidth;  // Non IE browser
     else if (document.documentElement && document.documentElement.clientWidth)
       width = document.documentElement.clientWidth;  // IE6
     else if (document.body && document.body.clientWidth)
       width = document.body.clientWidth; // IE4

     var height = 0;

     if ( typeof( window.innerHeight ) == 'number' )
       height = window.innerHeight;  // Non IE browser
     else if (document.documentElement && document.documentElement.clientHeight)
       height = document.documentElement.clientHeight;  // IE6
     else if (document.body && document.body.clientHeight)
       height = document.body.clientHeight; // IE4

     if (height && (width/height > 1.05*1024/768))
     {
       width = height * 1024.0/768;
     }

     // IE fires onresize even when only font size is changed!
     // so we do a check to avoid blocking < and > actions
     if (width != w3c_slidy.last_width || height != w3c_slidy.last_height)
     {
       if (width >= 1100)
         w3c_slidy.size_index = 5;    // 4
       else if (width >= 1000)
         w3c_slidy.size_index = 4;    // 3
       else if (width >= 800)
         w3c_slidy.size_index = 3;    // 2
       else if (width >= 600)
         w3c_slidy.size_index = 2;    // 1
       else if (width)
         w3c_slidy.size_index = 0;

       // add in font size adjustment from meta element e.g.
       // <meta name="font-size-adjustment" content="-2" />
       // useful when slides have too much content ;-)

       if (0 <= w3c_slidy.size_index + w3c_slidy.size_adjustment &&
             w3c_slidy.size_index + w3c_slidy.size_adjustment < w3c_slidy.sizes.length)
         w3c_slidy.size_index = w3c_slidy.size_index + w3c_slidy.size_adjustment;

       // enables cross browser use of relative width/height
       // on object elements for use with SVG and Flash media
       w3c_slidy.adjust_object_dimensions(width, height);

       if (document.body.style.fontSize != w3c_slidy.sizes[w3c_slidy.size_index])
       {
         document.body.style.fontSize = w3c_slidy.sizes[w3c_slidy.size_index];
       }

       w3c_slidy.last_width = width;
       w3c_slidy.last_height = height;

       // force reflow to work around Mozilla bug
       if (w3c_slidy.ns_pos)
       {
         var slide = w3c_slidy.slides[w3c_slidy.slide_number];
         w3c_slidy.hide_slide(slide);
         w3c_slidy.show_slide(slide);
       }

       // force correct positioning of toolbar
       w3c_slidy.refresh_toolbar(200);
     }
  },

  scrolled: function () {
    if (w3c_slidy.toolbar && !w3c_slidy.ns_pos && !w3c_slidy.ie7)
    {
      w3c_slidy.hack_offset = w3c_slidy.scroll_x_offset();
      // hide toolbar
      w3c_slidy.toolbar.style.display = "none";

      // make it reappear later
      if (w3c_slidy.scrollhack == 0 && !w3c_slidy.view_all)
      {
        setTimeout(function () {w3c_slidy.show_toolbar(); }, 1000);
        w3c_slidy.scrollhack = 1;
      }
    }
  },

  hide_toolbar: function () {
    w3c_slidy.add_class(w3c_slidy.toolbar, "hidden");
    window.focus();
  },

  // used to ensure IE refreshes toolbar in correct position
  refresh_toolbar: function (interval) {
    if (!w3c_slidy.ns_pos && !w3c_slidy.ie7)
    {
      w3c_slidy.hide_toolbar();
      setTimeout(function () {w3c_slidy.show_toolbar(); }, interval);
    }
  },

  // restores toolbar after short delay
  show_toolbar: function () {
    if (w3c_slidy.want_toolbar)
    {
      w3c_slidy.toolbar.style.display = "block";

      if (!w3c_slidy.ns_pos)
      {
        // adjust position to allow for scrolling
        var xoffset = w3c_slidy.scroll_x_offset();
        w3c_slidy.toolbar.style.left = xoffset;
        w3c_slidy.toolbar.style.right = xoffset;

        // determine vertical scroll offset
        //var yoffset = scrollYOffset();

        // bottom is doc height - window height - scroll offset
        //var bottom = documentHeight() - lastHeight - yoffset

        //if (yoffset > 0 || documentHeight() > lastHeight)
        //   bottom += 16;  // allow for height of scrollbar

        w3c_slidy.toolbar.style.bottom = 0; //bottom;
      }

      w3c_slidy.remove_class(w3c_slidy.toolbar, "hidden");
    }

    w3c_slidy.scrollhack = 0;


    // set the keyboard focus to the help link on the
    // toolbar to ensure that document has the focus
    // IE doesn't always work with window.focus()
    // and this hack has benefit of Enter for help

    try
    {
      if (!w3c_slidy.opera)
        w3c_slidy.help_anchor.focus();
    }
    catch (e)
    {
    }
  },

// invoked via F key
  toggle_toolbar: function () {
    if (!w3c_slidy.view_all)
    {
      if (w3c_slidy.has_class(w3c_slidy.toolbar, "hidden"))
      {
        w3c_slidy.remove_class(w3c_slidy.toolbar, "hidden")
        w3c_slidy.want_toolbar = 1;
      }
      else
      {
        w3c_slidy.add_class(w3c_slidy.toolbar, "hidden")
        w3c_slidy.want_toolbar = 0;
      }
    }
  },

  scroll_x_offset: function () {
    if (window.pageXOffset)
      return self.pageXOffset;

    if (document.documentElement &&
             document.documentElement.scrollLeft)
      return document.documentElement.scrollLeft;

    if (document.body)
      return document.body.scrollLeft;

    return 0;
  },

  scroll_y_offset: function () {
    if (window.pageYOffset)
      return self.pageYOffset;

    if (document.documentElement &&
             document.documentElement.scrollTop)
      return document.documentElement.scrollTop;

    if (document.body)
      return document.body.scrollTop;

    return 0;
  },

  // looking for a way to determine height of slide content
  // the slide itself is set to the height of the window
  optimize_font_size: function () {
    var slide = w3c_slidy.slides[w3c_slidy.slide_number];

    //var dh = documentHeight(); //getDocHeight(document);
    var dh = slide.scrollHeight;
    var wh = getWindowHeight();
    var u = 100 * dh / wh;

    alert("window utilization = " + u + "% (doc "
      + dh + " win " + wh + ")");
  },

  // from document object
  get_doc_height: function (doc) {
    if (!doc)
      doc = document;

    if (doc && doc.body && doc.body.offsetHeight)
      return doc.body.offsetHeight;  // ns/gecko syntax

    if (doc && doc.body && doc.body.scrollHeight)
      return doc.body.scrollHeight;

    alert("couldn't determine document height");
  },

  get_window_height: function () {
    if ( typeof( window.innerHeight ) == 'number' )
      return window.innerHeight;  // Non IE browser

    if (document.documentElement && document.documentElement.clientHeight)
      return document.documentElement.clientHeight;  // IE6

    if (document.body && document.body.clientHeight)
      return document.body.clientHeight; // IE4
  },

  document_height: function () {
    var sh, oh;

    sh = document.body.scrollHeight;
    oh = document.body.offsetHeight;

    if (sh && oh)
    {
      return (sh > oh ? sh : oh);
    }

    // no idea!
    return 0;
  },

  smaller: function () {
    if (w3c_slidy.size_index > 0)
    {
      --w3c_slidy.size_index;
    }

    w3c_slidy.toolbar.style.display = "none";
    document.body.style.fontSize = w3c_slidy.sizes[w3c_slidy.size_index];
    var slide = w3c_slidy.slides[w3c_slidy.slide_number];
    w3c_slidy.hide_slide(slide);
    w3c_slidy.show_slide(slide);
    setTimeout(function () {w3c_slidy.show_toolbar(); }, 50);
  },

  bigger: function () {
    if (w3c_slidy.size_index < w3c_slidy.sizes.length - 1)
    {
      ++w3c_slidy.size_index;
    }

    w3c_slidy.toolbar.style.display = "none";
    document.body.style.fontSize = w3c_slidy.sizes[w3c_slidy.size_index];
    var slide = w3c_slidy.slides[w3c_slidy.slide_number];
    w3c_slidy.hide_slide(slide);
    w3c_slidy.show_slide(slide);
    setTimeout(function () {w3c_slidy.show_toolbar(); }, 50);
  },

  // enables cross browser use of relative width/height
  // on object elements for use with SVG and Flash media
  // with thanks to Ivan Herman for the suggestion
  adjust_object_dimensions: function (width, height) {
    for( var i = 0; i < w3c_slidy.objects.length; i++ )
    {
      var obj = this.objects[i];
      var mimeType = obj.getAttribute("type");

      if (mimeType == "image/svg+xml" || mimeType == "application/x-shockwave-flash")
      {
        if ( !obj.initialWidth )
          obj.initialWidth = obj.getAttribute("width");

        if ( !obj.initialHeight )
          obj.initialHeight = obj.getAttribute("height");

        if ( obj.initialWidth && obj.initialWidth.charAt(obj.initialWidth.length-1) == "%" )
        {
          var w = parseInt(obj.initialWidth.slice(0, obj.initialWidth.length-1));
          var newW = width * (w/100.0);
          obj.setAttribute("width",newW);
        }

        if ( obj.initialHeight &&
             obj.initialHeight.charAt(obj.initialHeight.length-1) == "%" )
        {
          var h = parseInt(obj.initialHeight.slice(0, obj.initialHeight.length-1));
          var newH = height * (h/100.0);
          obj.setAttribute("height", newH);
        }
      }
    }
  },

  // needed for Opera to inhibit default behavior
  // since Opera delivers keyPress even if keyDown
  // was cancelled
  key_press: function (event) {
    if (!event)
      event = window.event;

    if (!w3c_slidy.key_wanted)
      return w3c_slidy.cancel(event);

    return true;
  },

  //  See e.g. http://www.quirksmode.org/js/events/keys.html for keycodes
  key_down: function (event) {
    var key, target, tag;

    w3c_slidy.key_wanted = true;

    if (!event)
      event = window.event;

    // kludge around NS/IE differences
    if (window.event)
    {
      key = window.event.keyCode;
      target = window.event.srcElement;
    }
    else if (event.which)
    {
      key = event.which;
      target = event.target;
    }
    else
      return true; // Yikes! unknown browser

    // ignore event if key value is zero
    // as for alt on Opera and Konqueror
    if (!key)
       return true;

    // avoid interfering with keystroke
    // behavior for non-slidy chrome elements
    if (!w3c_slidy.slidy_chrome(target) &&
        w3c_slidy.special_element(target))
      return true;

    // check for concurrent control/command/alt key
    // but are these only present on mouse events?

    if (event.ctrlKey || event.altKey || event.metaKey)
       return true;

    // dismiss table of contents if visible
    if (w3c_slidy.is_shown_toc() && key != 9 && key != 16 && key != 38 && key != 40)
    {
      w3c_slidy.hide_table_of_contents(true);

      if (key == 27 || key == 84 || key == 67)
        return w3c_slidy.cancel(event);
    }

    if (key == 34) // Page Down
    {
      if (w3c_slidy.view_all)
        return true;

      w3c_slidy.next_slide(false);
      return w3c_slidy.cancel(event);
    }
    else if (key == 33) // Page Up
    {
      if (w3c_slidy.view_all)
        return true;

      w3c_slidy.previous_slide(false);
      return w3c_slidy.cancel(event);
    }
    else if (key == 32) // space bar
    {
      w3c_slidy.next_slide(true);
      return w3c_slidy.cancel(event);
    }
    else if (key == 37) // Left arrow
    {
      w3c_slidy.previous_slide(!event.shiftKey);
      return w3c_slidy.cancel(event);
    }
    else if (key == 36) // Home
    {
      w3c_slidy.first_slide();
      return w3c_slidy.cancel(event);
    }
    else if (key == 35) // End
    {
      w3c_slidy.last_slide();
      return w3c_slidy.cancel(event);
    }
    else if (key == 39) // Right arrow
    {
      w3c_slidy.next_slide(!event.shiftKey);
      return w3c_slidy.cancel(event);
    }
    else if (key == 13) // Enter
    {
      if (w3c_slidy.outline)
      {
        if (w3c_slidy.outline.visible)
          w3c_slidy.fold(w3c_slidy.outline);
        else
          w3c_slidy.unfold(w3c_slidy.outline);

       return w3c_slidy.cancel(event);
      }
    }
    else if (key == 188)  // < for smaller fonts
    {
      w3c_slidy.smaller();
      return w3c_slidy.cancel(event);
    }
    else if (key == 190)  // > for larger fonts
    {
      w3c_slidy.bigger();
      return w3c_slidy.cancel(event);
    }
    else if (key == 189 || key == 109)  // - for smaller fonts
    {
      w3c_slidy.smaller();
      return w3c_slidy.cancel(event);
    }
    else if (key == 187 || key == 191 || key == 107)  // = +  for larger fonts
    {
      w3c_slidy.bigger();
      return w3c_slidy.cancel(event);
    }
    else if (key == 83)  // S for smaller fonts
    {
      w3c_slidy.smaller();
      return w3c_slidy.cancel(event);
    }
    else if (key == 66)  // B for larger fonts
    {
      w3c_slidy.bigger();
      return w3c_slidy.cancel(event);
    }
    else if (key == 90)  // Z for last slide
    {
      w3c_slidy.last_slide();
      return w3c_slidy.cancel(event);
    }
    else if (key == 70)  // F for toggle toolbar
    {
      w3c_slidy.toggle_toolbar();
      return w3c_slidy.cancel(event);
    }
    else if (key == 65)  // A for toggle view single/all slides
    {
      w3c_slidy.toggle_view();
      return w3c_slidy.cancel(event);
    }
    else if (key == 75)  // toggle action of left click for next page
    {
      w3c_slidy.mouse_click_enabled = !w3c_slidy.mouse_click_enabled;
      var alert_msg = (w3c_slidy.mouse_click_enabled ?
                "enabled" : "disabled") +  " mouse click advance";

      alert(w3c_slidy.localize(alert_msg));
      return w3c_slidy.cancel(event);
    }
    else if (key == 84 || key == 67)  // T or C for table of contents
    {
      if (w3c_slidy.toc)
        w3c_slidy.toggle_table_of_contents();

      return w3c_slidy.cancel(event);
    }
    else if (key == 72) // H for help
    {
      window.location = w3c_slidy.help_page;
      return w3c_slidy.cancel(event);
    }
//jmi
    else if (key == 73) // I to toggle incremental display
    {
      var slide = w3c_slidy.slides[w3c_slidy.slide_number];
      w3c_slidy.hide_slide(slide);
      if (w3c_slidy.incremental_display) { w3c_slidy.set_visibility_all_incremental("visible"); }
      w3c_slidy.incremental_display = !w3c_slidy.incremental_display ;
      w3c_slidy.last_shown = null ;
      w3c_slidy.set_visibility_all_incremental("hidden");
      //this.set_eos_status(true);
      w3c_slidy.show_slide(slide);
      return w3c_slidy.cancel(event);
    }
    else if (key == 76) // L to toggle color-set
    {
      w3c_slidy.toggle_color_set();
      return w3c_slidy.cancel(event);
    }
    else if (key == 77) // display help_keymap
    {
      alert(w3c_slidy.help_keymap);
      return w3c_slidy.cancel(event);
    }
//jmi end
     //else alert("key code is "+ key);
    return true;
  },

  // safe for both text/html and application/xhtml+xml
  create_element: function (name) {
    if (this.xhtml && (typeof document.createElementNS != 'undefined'))
      return document.createElementNS("http://www.w3.org/1999/xhtml", name)

    return document.createElement(name);
  },

  get_element_style: function (elem, IEStyleProp, CSSStyleProp) {
    if (elem.currentStyle)
    {
      return elem.currentStyle[IEStyleProp];
    }
    else if (window.getComputedStyle)
    {
      var compStyle = window.getComputedStyle(elem, "");
      return compStyle.getPropertyValue(CSSStyleProp);
    }
    return "";
  },

  // the string str is a whitespace separated list of tokens
  // test if str contains a particular token, e.g. "slide"
  has_token: function (str, token) {
    if (str)
    {
      // define pattern as regular expression
      var pattern = /\w+/g;

      // check for matches
      // place result in array
      var result = str.match(pattern);

      // now check if desired token is present
      for (var i = 0; i < result.length; i++)
      {
        if (result[i] == token)
          return true;
      }
    }

    return false;
  },

  get_class_list: function (element) {
    if (typeof element.className != 'undefined')
      return element.className;

    return element.getAttribute("class");
  },

  has_class: function (element, name) {
    if (element.nodeType != 1)
      return false;

    var regexp = new RegExp("(^| )" + name + "\W*");

    if (typeof element.className != 'undefined')
      return regexp.test(element.className);

    return regexp.test(element.getAttribute("class"));
  },

  remove_class: function (element, name) {
    var regexp = new RegExp("(^| )" + name + "\W*");
    var clsval = "";

    if (typeof element.className != 'undefined')
    {
      clsval = element.className;

      if (clsval)
      {
        clsval = clsval.replace(regexp, "");
        element.className = clsval;
      }
    }
    else
    {
      clsval = element.getAttribute("class");

      if (clsval)
      {
        clsval = clsval.replace(regexp, "");
        element.setAttribute("class", clsval);
      }
    }
  },

  add_class: function (element, name) {
    if (!this.has_class(element, name))
    {
      if (typeof element.className != 'undefined')
        element.className += " " + name;
      else
      {
        var clsval = element.getAttribute("class");
        clsval = clsval ? clsval + " " + name : name;
        element.setAttribute("class", clsval);
      }
    }
  },

  // HTML elements that can be used with class="incremental"
  // note that you can also put the class on containers like
  // up, ol, dl, and div to make their contents appear
  // incrementally. Upper case is used since this is what
  // browsers report for HTML node names (text/html).
  incremental_elements: null,
  okay_for_incremental: function (name) {
    if (!this.incremental_elements)
    {
      var inclist = new Array();
      inclist["p"] = true;
      inclist["pre"] = true;
      inclist["li"] = true;
      inclist["blockquote"] = true;
      inclist["dt"] = true;
      inclist["dd"] = true;
      inclist["h2"] = true;
      inclist["h3"] = true;
      inclist["h4"] = true;
      inclist["h5"] = true;
      inclist["h6"] = true;
      inclist["span"] = true;
      inclist["address"] = true;
      inclist["table"] = true;
      inclist["tr"] = true;
      inclist["th"] = true;
      inclist["td"] = true;
      inclist["img"] = true;
      inclist["object"] = true;
      this.incremental_elements = inclist;
    }
    return this.incremental_elements[name.toLowerCase()];
  },

  next_incremental_item: function (node) {
    var br = this.is_xhtml ? "br" : "BR";
    var slide = w3c_slidy.slides[w3c_slidy.slide_number];

    for (;;)
    {
      node = w3c_slidy.next_node(slide, node);

      if (node == null || node.parentNode == null)
        break;

      if (node.nodeType == 1)  // ELEMENT
      {
        if (node.nodeName == br)
          continue;

        if (w3c_slidy.has_class(node, "incremental")
             && w3c_slidy.okay_for_incremental(node.nodeName))
          return node;

        if (w3c_slidy.has_class(node.parentNode, "incremental")
             && !w3c_slidy.has_class(node, "non-incremental"))
          return node;
      }
    }

    return node;
  },

  previous_incremental_item: function (node) {
    var br = this.is_xhtml ? "br" : "BR";
    var slide = w3c_slidy.slides[w3c_slidy.slide_number];

    for (;;)
    {
      node = w3c_slidy.previous_node(slide, node);

      if (node == null || node.parentNode == null)
        break;

      if (node.nodeType == 1)
      {
        if (node.nodeName == br)
          continue;

        if (w3c_slidy.has_class(node, "incremental")
             && w3c_slidy.okay_for_incremental(node.nodeName))
          return node;

        if (w3c_slidy.has_class(node.parentNode, "incremental")
             && !w3c_slidy.has_class(node, "non-incremental"))
          return node;
      }
    }

    return node;
  },

  // set visibility for all elements on current slide with
  // a parent element with attribute class="incremental"
  set_visibility_all_incremental: function (value) {
    var node = this.next_incremental_item(null);

//jmi
if (!w3c_slidy.incremental_display) {value = "visible";}

    if (value == "hidden")
    {
      while (node)
      {
        w3c_slidy.add_class(node, "invisible");
        node = w3c_slidy.next_incremental_item(node);
      }
    }
    else // value == "visible"
    {
      while (node)
      {
        w3c_slidy.remove_class(node, "invisible");
        node = w3c_slidy.next_incremental_item(node);
      }
    }
  },

  // reveal the next hidden item on the slide
  // node is null or the node that was last revealed
  reveal_next_item: function (node) {
    node = w3c_slidy.next_incremental_item(node);

    if (node && node.nodeType == 1)  // an element
      w3c_slidy.remove_class(node, "invisible");

    return node;
  },

  // exact inverse of revealNextItem(node)
  hide_previous_item: function (node) {
    if (node && node.nodeType == 1)  // an element
      w3c_slidy.add_class(node, "invisible");

    return this.previous_incremental_item(node);
  },

  // left to right traversal of root's content
  next_node: function (root, node) {
    if (node == null)
      return root.firstChild;

    if (node.firstChild)
      return node.firstChild;

    if (node.nextSibling)
      return node.nextSibling;

    for (;;)
    {
      node = node.parentNode;

      if (!node || node == root)
        break;

      if (node && node.nextSibling)
        return node.nextSibling;
    }

    return null;
  },

  // right to left traversal of root's content
  previous_node: function (root, node) {
    if (node == null)
    {
      node = root.lastChild;

      if (node)
      {
        while (node.lastChild)
          node = node.lastChild;
      }

      return node;
    }

    if (node.previousSibling)
    {
      node = node.previousSibling;

      while (node.lastChild)
        node = node.lastChild;

      return node;
    }

    if (node.parentNode != root)
      return node.parentNode;

    return null;
  },

  previous_sibling_element: function (el) {
    el = el.previousSibling;

    while (el && el.nodeType != 1)
      el = el.previousSibling;

    return el;
  },

  next_sibling_element: function (el) {
    el = el.nextSibling;

    while (el && el.nodeType != 1)
      el = el.nextSibling;

    return el;
  },

  first_child_element: function (el) {
    var node;

    for (node = el.firstChild; node; node = node.nextSibling)
    {
      if (node.nodeType == 1)
        break;
    }

    return node;
  },

  first_tag: function (element, tag) {
    var node;

    if (!this.is_xhtml)
      tag = tag.toUpperCase();

    for (node = element.firstChild; node; node = node.nextSibling)
    {
      if (node.nodeType == 1 && node.nodeName == tag)
        break;
    }

    return node;
  },

  hide_selection: function () {
    if (window.getSelection) // Firefox, Chromium, Safari, Opera
    {
      var selection = window.getSelection();

      if (selection.rangeCount > 0)
      {
        var range = selection.getRangeAt(0);
        range.collapse (false);
      }
    }
    else // Internet Explorer
    {
      var textRange = document.selection.createRange ();
      textRange.collapse (false);
    }
  },

  get_selected_text: function () {
    try
    {
      if (window.getSelection)
        return window.getSelection().toString();

      if (document.getSelection)
        return document.getSelection().toString();

      if (document.selection)
        return document.selection.createRange().text;
    }
    catch (e)
    {
    }

    return "";
  },

  // make note of length of selected text
  // as this evaluates to zero in click event
  mouse_button_up: function (e) {
    w3c_slidy.selected_text_len = w3c_slidy.get_selected_text().length;
  },

  // right mouse button click is reserved for context menus
  // it is more reliable to detect rightclick than leftclick
  mouse_button_click: function (e) {
    var rightclick = false;
    var leftclick = false;
    var middleclick = false;
    var target;

    if (!e)
      var e = window.event;

    if (e.target)
      target = e.target;
    else if (e.srcElement)
      target = e.srcElement;

    // work around Safari bug
    if (target.nodeType == 3)
      target = target.parentNode;

    if (e.which) // all browsers except IE
    {
      leftclick = (e.which == 1);
      middleclick = (e.which == 2);
      rightclick = (e.which == 3);
    }
    else if (e.button)
    {
      // Konqueror gives 1 for left, 4 for middle
      // IE6 gives 0 for left and not 1 as I expected

      if (e.button == 4)
        middleclick = true;

      // all browsers agree on 2 for right button
      rightclick = (e.button == 2);
    }
    else
      leftclick = true;

    if (w3c_slidy.selected_text_len > 0)
    {
      w3c_slidy.stop_propagation(e);
      e.cancel = true;
      e.returnValue = false;
      return false;
    }

    // dismiss table of contents
    w3c_slidy.hide_table_of_contents(false);

    // check if target is something that probably want's clicks
    // e.g. a, embed, object, input, textarea, select, option
    var tag = target.nodeName.toLowerCase();

    if (w3c_slidy.mouse_click_enabled && leftclick &&
        !w3c_slidy.special_element(target) &&
        !target.onclick)
    {
      w3c_slidy.next_slide(true);
      w3c_slidy.stop_propagation(e);
      e.cancel = true;
      e.returnValue = false;
      return false;
    }

    return true;
  },

  special_element: function (e) {
    var tag = e.nodeName.toLowerCase();

    return e.onkeydown ||
      e.onclick ||
      tag == "a" ||
      tag == "embed" ||
      tag == "object" ||
      tag == "video" ||
      tag == "audio" ||
      tag == "input" ||
      tag == "textarea" ||
      tag == "select" ||
      tag == "option";
  },

  slidy_chrome: function (el) {
    while (el)
    {
      if (el == w3c_slidy.toc ||
          el == w3c_slidy.toolbar ||
          w3c_slidy.has_class(el, "outline"))
        return true;

      el = el.parentNode;
    }

    return false;
  },

  get_key: function (e)
  {
    var key;

    // kludge around NS/IE differences
    if (typeof window.event != "undefined")
      key = window.event.keyCode;
    else if (e.which)
      key = e.which;

    return key;
  },

  get_target: function (e) {
    var target;

    if (!e)
      e = window.event;

    if (e.target)
      target = e.target;
    else if (e.srcElement)
      target = e.srcElement;

    if (target.nodeType != 1)
      target = target.parentNode;

    return target;
  },

  // does display property provide correct defaults?
  is_block: function (elem) {
    var tag = elem.nodeName.toLowerCase();

    return tag == "ol" || tag == "ul" || tag == "p" ||
           tag == "li" || tag == "table" || tag == "pre" ||
           tag == "h1" || tag == "h2" || tag == "h3" ||
           tag == "h4" || tag == "h5" || tag == "h6" ||
           tag == "blockquote" || tag == "address";
  },

  add_listener: function (element, event, handler) {
    if (window.addEventListener)
      element.addEventListener(event, handler, false);
    else
      element.attachEvent("on"+event, handler);
  },

  // used to prevent event propagation from field controls
  stop_propagation: function (event) {
    event = event ? event : window.event;
    event.cancelBubble = true;  // for IE

    if (event.stopPropagation)
      event.stopPropagation();

    return true;
  },

  cancel: function (event) {
    if (event)
    {
       event.cancel = true;
       event.returnValue = false;

      if (event.preventDefault)
        event.preventDefault();
    }

    w3c_slidy.key_wanted = false;
    return false;
  },
// jmi
  init_color_sets: function(){
   if (this.color_sets.length == 0){
     // initialize color_sets array
     var tmp = document.styleSheets;
     var j = 0;
     for (var i=0;i<tmp.length;i++) {
       var css_name = null ;
       if (tmp[i].title) {
	css_name = tmp[i].title ;
       }
       if ((tmp[i].href) && (tmp[i].href.indexOf('.css') != -1)) {
	css_name = tmp[i].href.substring(tmp[i].href.lastIndexOf('/')+1,tmp[i].href.indexOf('.css')) ;
       }
	if ((css_name) && (css_name.indexOf('color_set') > 0)) {
         this.color_sets[j] = tmp[i];
         this.color_sets[j++].disabled = true;
	}
     }
     if (this.color_sets.length > 0){ this.color_sets[0].disabled = false; }
   }
  },
  toggle_color_set: function(){
   // toggle to the next color_set
   if (this.color_sets.length > 0){
    var i = 0;
    while ((i < this.color_sets.length) && (this.color_sets[i].disabled == true)) { i = i + 1 ; }
    if (i == this.color_sets.length) { i = i - 1; }
    this.color_sets[i].disabled = true ;
    this.color_sets[(i + 1) % (this.color_sets.length)].disabled = false ;
   }
  },

// for each language define an associative array
// and also the help text which is longer

  strings_es: {
    "slide":"pág.",
    "help?":"Ayuda",
    "contents?":"Índice",
    "table of contents":"tabla de contenidos",
    "Table of Contents":"Tabla de Contenidos",
    "restart presentation":"Reiniciar presentación",
    "restart?":"Inicio"
  },
  help_es:
    "Utilice el ratón, barra espaciadora, teclas Izda/Dcha, " +
    "o Re pág y Av pág. Use S y B para cambiar el tamaño de fuente.",

  strings_ca: {
    "slide":"pàg..",
    "help?":"Ajuda",
    "contents?":"Índex",
    "table of contents":"taula de continguts",
    "Table of Contents":"Taula de Continguts",
    "restart presentation":"Reiniciar presentació",
    "restart?":"Inici"
  },
  help_ca:
    "Utilitzi el ratolí, barra espaiadora, tecles Esq./Dta. " +
    "o Re pàg y Av pàg. Usi S i B per canviar grandària de font.",

  strings_cs: {
    "slide":"snímek",
    "help?":"nápověda",
    "contents?":"obsah",
    "table of contents":"obsah prezentace",
    "Table of Contents":"Obsah prezentace",
    "restart presentation":"znovu spustit prezentaci",
    "restart?":"restart"
  },
  help_cs:
    "Prezentaci můžete procházet pomocí kliknutí myši, mezerníku, " +
    "šipek vlevo a vpravo nebo kláves PageUp a PageDown. Písmo se " +
    "dá zvětšit a zmenšit pomocí kláves B a S.",

  strings_nl: {
    "slide":"pagina",
    "help?":"Help?",
    "contents?":"Inhoud?",
    "table of contents":"inhoudsopgave",
    "Table of Contents":"Inhoudsopgave",
    "restart presentation":"herstart presentatie",
    "restart?":"Herstart?"
  },
  help_nl:
     "Navigeer d.m.v. het muis, spatiebar, Links/Rechts toetsen, " +
     "of PgUp en PgDn. Gebruik S en B om de karaktergrootte te veranderen.",

  strings_de: {
    "slide":"Seite",
    "help?":"Hilfe",
    "contents?":"Übersicht",
    "table of contents":"Inhaltsverzeichnis",
    "Table of Contents":"Inhaltsverzeichnis",
    "restart presentation":"Präsentation neu starten",
    "restart?":"Neustart"
  },
  help_de:
    "Benutzen Sie die Maus, Leerschlag, die Cursortasten links/rechts oder " +
    "Page up/Page Down zum Wechseln der Seiten und S und B für die Schriftgrösse.",

  strings_pl: {
    "slide":"slajd",
    "help?":"pomoc?",
    "contents?":"spis treści?",
    "table of contents":"spis treści",
    "Table of Contents":"Spis Treści",
    "restart presentation":"Restartuj prezentację",
    "restart?":"restart?"
  },
  help_pl:
    "Zmieniaj slajdy klikając myszą, naciskając spację, strzałki lewo/prawo" +
    "lub PgUp / PgDn. Użyj klawiszy S i B, aby zmienić rozmiar czczionki.",

  strings_fr: {
    "slide":"page",
    "help?":"Aide",
    "contents?":"Index",
    "table of contents":"table des matières",
    "Table of Contents":"Table des matières",
    "restart presentation":"Recommencer l'exposé",
    "restart?":"Début"
  },
  help_fr:
    "Naviguez avec la souris, la barre d'espace, les flèches " +
    "gauche/droite ou les touches Pg Up, Pg Dn. Utilisez " +
    "les touches S et B pour modifier la taille de la police, M pour l'association des touches.",

  strings_hu: {
    "slide":"oldal",
    "help?":"segítség",
    "contents?":"tartalom",
    "table of contents":"tartalomjegyzék",
    "Table of Contents":"Tartalomjegyzék",
    "restart presentation":"bemutató újraindítása",
    "restart?":"újraindítás"
  },
  help_hu:
    "Az oldalak közti lépkedéshez kattintson az egérrel, vagy " +
    "használja a szóköz, a bal, vagy a jobb nyíl, illetve a Page Down, " +
    "Page Up billentyűket. Az S és a B billentyűkkel változtathatja " +
    "a szöveg méretét.",

  strings_it: {
    "slide":"pag.",
    "help?":"Aiuto",
    "contents?":"Indice",
    "table of contents":"indice",
    "Table of Contents":"Indice",
    "restart presentation":"Ricominciare la presentazione",
    "restart?":"Inizio"
  },
  help_it:
    "Navigare con mouse, barra spazio, frecce sinistra/destra o " +
    "PgUp e PgDn. Usare S e B per cambiare la dimensione dei caratteri.",

  strings_el: {
    "slide":"σελίδα",
    "help?":"βοήθεια;",
    "contents?":"περιεχόμενα;",
    "table of contents":"πίνακας περιεχομένων",
    "Table of Contents":"Πίνακας Περιεχομένων",
    "restart presentation":"επανεκκίνηση παρουσίασης",
    "restart?":"επανεκκίνηση;"
  },
  help_el:
    "Πλοηγηθείτε με το κλίκ του ποντικιού, το space, τα βέλη αριστερά/δεξιά, " +
    "ή Page Up και Page Down. Χρησιμοποιήστε τα πλήκτρα S και B για να αλλάξετε " +
    "το μέγεθος της γραμματοσειράς.",

  strings_ja: {
    "slide":"スライド",
    "help?":"ヘルプ",
    "contents?":"目次",
    "table of contents":"目次を表示",
    "Table of Contents":"目次",
    "restart presentation":"最初から再生",
    "restart?":"最初から"
  },
  help_ja:
     "マウス左クリック ・ スペース ・ 左右キー " +
     "または Page Up ・ Page Downで操作， S ・ Bでフォントサイズ変更",

  strings_zh: {
    "slide":"幻灯片",
    "help?":"帮助?",
    "contents?":"内容?",
    "table of contents":"目录",
    "Table of Contents":"目录",
    "restart presentation":"重新启动展示",
    "restart?":"重新启动?"
  },
  help_zh:
    "用鼠标点击, 空格条, 左右箭头, Pg Up 和 Pg Dn 导航. " +
    "用 S, B 改变字体大小.",

  strings_ru: {
    "slide":"слайд",
    "help?":"помощь?",
    "contents?":"содержание?",
    "table of contents":"оглавление",
    "Table of Contents":"Оглавление",
    "restart presentation":"перезапустить презентацию",
    "restart?":"перезапуск?"
  },
  help_ru:
    "Перемещайтесь кликая мышкой, используя клавишу пробел, стрелки" +
    "влево/вправо или Pg Up и Pg Dn. Клавиши S и B меняют размер шрифта.",

  strings_sv: {
    "slide":"sida",
    "help?":"hjälp",
    "contents?":"innehåll",
    "table of contents":"innehållsförteckning",
    "Table of Contents":"Innehållsförteckning",
    "restart presentation":"visa presentationen från början",
    "restart?":"börja om"
  },
  help_sv:
    "Bläddra med ett klick med vänstra musknappen, mellanslagstangenten, " +
    "vänster- och högerpiltangenterna eller tangenterna Pg Up, Pg Dn. " +
    "Använd tangenterna S och B för att ändra textens storlek.",

  strings: { },

  localize: function (src) {
    if (src == "")
      return src;

     // try full language code, e.g. en-US
     var s, lookup = w3c_slidy.strings[w3c_slidy.lang];

     if (lookup)
     {
       s = lookup[src];

       if (s)
        return s;
     }

     // strip country code suffix, e.g.
     // try en if undefined for en-US
     var lg = w3c_slidy.lang.split("-");

     if (lg.length > 1)
     {
       lookup = w3c_slidy.strings[lg[0]];

       if (lookup)
       {
         s = lookup[src];

         if (s)
          return s;
       }
     }

     // otherwise string as is
     return src;
  },

  init_localization: function () {
    var i18n = w3c_slidy;
    var help_text = w3c_slidy.help_text;

    // each such language array is declared in the localize array
    // this is used as in  w3c_slidy.localize("foo");
    this.strings = {
      "es":this.strings_es,
      "ca":this.strings_ca,
      "cs":this.strings_cs,
      "nl":this.strings_nl,
      "de":this.strings_de,
      "pl":this.strings_pl,
      "fr":this.strings_fr,
      "hu":this.strings_hu,
      "it":this.strings_it,
      "el":this.strings_el,
      "jp":this.strings_ja,
      "zh":this.strings_zh,
      "ru":this.strings_ru,
      "sv":this.strings_sv
    },

    i18n.strings_es[help_text] = i18n.help_es;
    i18n.strings_ca[help_text] = i18n.help_ca;
    i18n.strings_cs[help_text] = i18n.help_cs;
    i18n.strings_nl[help_text] = i18n.help_nl;
    i18n.strings_de[help_text] = i18n.help_de;
    i18n.strings_pl[help_text] = i18n.help_pl;
    i18n.strings_fr[help_text] = i18n.help_fr;
    i18n.strings_hu[help_text] = i18n.help_hu;
    i18n.strings_it[help_text] = i18n.help_it;
    i18n.strings_el[help_text] = i18n.help_el;
    i18n.strings_ja[help_text] = i18n.help_ja;
    i18n.strings_zh[help_text] = i18n.help_zh;
    i18n.strings_ru[help_text] = i18n.help_ru;
    i18n.strings_sv[help_text] = i18n.help_sv;

    w3c_slidy.lang = document.body.parentNode.getAttribute("lang");

    if (!w3c_slidy.lang)
      w3c_slidy.lang = document.body.parentNode.getAttribute("xml:lang");

    if (!w3c_slidy.lang)
      w3c_slidy.lang = "en";
  }
};

// hack for back button behavior
if (w3c_slidy.ie6 || w3c_slidy.ie7)
{
  document.write("<iframe id='historyFrame' " +
  "src='javascript:\"<html"+"></"+"html>\"' " +
  "height='1' width='1' " +
  "style='position:absolute;left:-800px'></iframe>");
}

// attach event listeners for initialization
w3c_slidy.set_up();

// hide the slides as soon as body element is available
// to reduce annoying screen mess before the onload event
setTimeout(w3c_slidy.hide_slides, 50);

/*]]>*/
</script>
</head>
<body class="article">
<div id="header" class="slide">
<h1>AsciiDoc User Guide</h1>
<span id="author">Stuart Rackham</span><br />
<span id="email"><tt>&lt;<a href="mailto:srackham@gmail.com">srackham@gmail.com</a>&gt;</tt></span><br />
</div>
<div class="slide">
<div id="preamble">
<h1 style="visibility: hidden;">Preamble</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="Preamble";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc is a text document format for writing notes, documentation,
articles, books, ebooks, slideshows, web pages, blogs and UNIX man
pages.  AsciiDoc files can be translated to many formats including
HTML, PDF, EPUB, man page.  AsciiDoc is highly configurable: both the
AsciiDoc source file syntax and the backend output markups (which can
be almost any type of SGML/XML markup) can be customized and extended
by the user.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="title">This document</div>
<div class="paragraph">
<p>This is an overly large document, it probably needs to be refactored
into a Tutorial, Quick Reference and Formal Reference.</p>
</div>
<div class="paragraph">
<p>If you&#8217;re new to AsciiDoc read this section and the <a href="#X6">Getting Started</a> section and take a look at the example AsciiDoc (<tt>*.txt</tt>)
source files in the distribution <tt>doc</tt> directory.</p>
</div>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_introduction">1. Introduction</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="1. Introduction";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc is a plain text human readable/writable document format that
can be translated to DocBook or HTML using the <tt>asciidoc(1)</tt> command.
You can then either use <tt>asciidoc(1)</tt> generated HTML directly or run
<tt>asciidoc(1)</tt> DocBook output through your favorite DocBook toolchain or
use the AsciiDoc <tt>a2x(1)</tt> toolchain wrapper to produce PDF, EPUB, DVI,
LaTeX, PostScript, man page, HTML and text formats.</p>
</div>
<div class="paragraph">
<p>The AsciiDoc format is a useful presentation format in its own right:
AsciiDoc markup is simple, intuitive and as such is easily proofed and
edited.</p>
</div>
<div class="paragraph">
<p>AsciiDoc is light weight: it consists of a single Python script and a
bunch of configuration files. Apart from <tt>asciidoc(1)</tt> and a Python
interpreter, no other programs are required to convert AsciiDoc text
files to DocBook or HTML. See <a href="#X11">Example AsciiDoc Documents</a>
below.</p>
</div>
<div class="paragraph">
<p>Text markup conventions tend to be a matter of (often strong) personal
preference: if the default syntax is not to your liking you can define
your own by editing the text based <tt>asciidoc(1)</tt> configuration files.
You can also create configuration files to translate AsciiDoc
documents to almost any SGML/XML markup.</p>
</div>
<div class="paragraph">
<p><tt>asciidoc(1)</tt> comes with a set of configuration files to translate
AsciiDoc articles, books and man pages to HTML or DocBook backend
formats.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="title">My AsciiDoc Itch</div>
<div class="paragraph">
<p>DocBook has emerged as the de facto standard Open Source documentation
format. But DocBook is a complex language, the markup is difficult to
read and even more difficult to write directly&#8201;&#8212;&#8201;I found I was
spending more time typing markup tags, consulting reference manuals
and fixing syntax errors, than I was writing the documentation.</p>
</div>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X6">2. Getting Started</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="2. Getting Started";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="_installing_asciidoc">2.1. Installing AsciiDoc</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="2.1. Installing AsciiDoc";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>See the <tt>README</tt> and <tt>INSTALL</tt> files for install prerequisites and
procedures. Packagers take a look at <a href="#X38">Packager Notes</a>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="X11">2.2. Example AsciiDoc Documents</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="2.2. Example AsciiDoc Documents";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The best way to quickly get a feel for AsciiDoc is to view the
AsciiDoc web site and/or distributed examples:</p>
</div>
<ul class="">
<li>
<span>
Take a look at the linked examples on the AsciiDoc web site home
  page <a href="http://www.methods.co.nz/asciidoc/">http://www.methods.co.nz/asciidoc/</a>.  Press the <em>Page Source</em> sidebar menu item to view
  corresponding AsciiDoc source.
</span>
</li>
<li>
<span>
Read the <tt>*.txt</tt> source files in the distribution <tt>./doc</tt> directory
  along with the corresponding HTML and DocBook XML files.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_asciidoc_document_types">3. AsciiDoc Document Types</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="3. AsciiDoc Document Types";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>There are three types of AsciiDoc documents: article, book and
manpage. All document types share the same AsciiDoc format with some
minor variations. If you are familiar with DocBook you will have
noticed that AsciiDoc document types correspond to the same-named
DocBook document types.</p>
</div>
<div class="paragraph">
<p>Use the <tt>asciidoc(1)</tt> <tt>-d</tt> (<tt>--doctype</tt>) option to specify the AsciiDoc
document type&#8201;&#8212;&#8201;the default document type is <em>article</em>.</p>
</div>
<div class="paragraph">
<p>By convention the <tt>.txt</tt> file extension is used for AsciiDoc document
source files.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="_article">3.1. article</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="3.1. article";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Used for short documents, articles and general documentation.  See the
AsciiDoc distribution <tt>./doc/article.txt</tt> example.</p>
</div>
<div class="paragraph">
<p>AsciiDoc defines standard DocBook article frontmatter and backmatter
<a href="#X93">section markup templates</a> (appendix, abstract, bibliography,
glossary, index).</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_book">3.2. book</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="3.2. book";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Books share the same format as articles, with the following
differences:</p>
</div>
<ul class="">
<li>
<span>
The part titles in multi-part books are <a href="#X17">top level titles</a>
  (same level as book title).
</span>
</li>
<li>
<span>
Some sections are book specific e.g. preface and colophon.
</span>
</li>
</ul>
<div class="paragraph">
<p>Book documents will normally be used to produce DocBook output since
DocBook processors can automatically generate footnotes, table of
contents, list of tables, list of figures, list of examples and
indexes.</p>
</div>
<div class="paragraph">
<p>AsciiDoc defines standard DocBook book frontmatter and backmatter
<a href="#X93">section markup templates</a> (appendix, dedication, preface,
bibliography, glossary, index, colophon).</p>
</div>
<div class="dlist"><div class="title">Example book documents</div><dl class="">
<dt class="hdlist1">
Book
</dt>
<dd>
<p>
  The <tt>./doc/book.txt</tt> file in the AsciiDoc distribution.
</p>
</dd>
<dt class="hdlist1">
Multi-part book
</dt>
<dd>
<p>
  The <tt>./doc/book-multi.txt</tt> file in the AsciiDoc distribution.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_manpage">3.3. manpage</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="3.3. manpage";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Used to generate roff format UNIX manual pages.  AsciiDoc manpage
documents observe special header title and section naming conventions&#8201;&#8212;&#8201;see the <a href="#X1">Manpage Documents</a> section for details.</p>
</div>
<div class="paragraph">
<p>AsciiDoc defines the <em>synopsis</em> <a href="#X93">section markup template</a> to
generate the DocBook <tt>refsynopsisdiv</tt> section.</p>
</div>
<div class="paragraph">
<p>See also the <tt>asciidoc(1)</tt> man page source (<tt>./doc/asciidoc.1.txt</tt>) from
the AsciiDoc distribution.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X5">4. AsciiDoc Backends</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="4. AsciiDoc Backends";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <tt>asciidoc(1)</tt> command translates an AsciiDoc formatted file to the
backend format specified by the <tt>-b</tt> (<tt>--backend</tt>) command-line
option. <tt>asciidoc(1)</tt> itself has little intrinsic knowledge of backend
formats, all translation rules are contained in customizable cascading
configuration files. Backend specific attributes are listed in the
<a href="#X88">Backend Attributes</a> section.</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
docbook45
</dt>
<dd>
<p>
  Outputs DocBook XML 4.5 markup.
</p>
</dd>
<dt class="hdlist1">
html4
</dt>
<dd>
<p>
  This backend generates plain HTML 4.01 Transitional markup.
</p>
</dd>
<dt class="hdlist1">
xhtml11
</dt>
<dd>
<p>
  This backend generates XHTML 1.1 markup styled with CSS2. Output
  files have an <tt>.html</tt> extension.
</p>
</dd>
<dt class="hdlist1">
html5
</dt>
<dd>
<p>
  This backend generates HTML 5 markup, apart from the inclusion of
  <a href="#X98">audio and video block macros</a> it is functionally identical to
  the <em>xhtml11</em> backend.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
slidy
</dt>
<dd>
<p>
  Use this backend to generate self-contained
  <a href="http://www.w3.org/Talks/Tools/Slidy2/">Slidy</a> HTML slideshows for
  your web browser from AsciiDoc documents. The Slidy backend is
  documented in the distribution <tt>doc/slidy.txt</tt> file and
  <a href="http://www.methods.co.nz/asciidoc/slidy.html">online</a>.
</p>
</dd>
<dt class="hdlist1">
wordpress
</dt>
<dd>
<p>
  A minor variant of the <em>html4</em> backend to support
  <a href="http://srackham.wordpress.com/blogpost1/">blogpost</a>.
</p>
</dd>
<dt class="hdlist1">
latex
</dt>
<dd>
<p>
  Experimental LaTeX backend.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_backend_aliases">4.1. Backend Aliases</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="4.1. Backend Aliases";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Backend aliases are alternative names for AsciiDoc backends.  AsciiDoc
comes with two backend aliases: <em>html</em> (aliased to <em>xhtml11</em>) and
<em>docbook</em> (aliased to <em>docbook45</em>).</p>
</div>
<div class="paragraph">
<p>You can assign (or reassign) backend aliases by setting an AsciiDoc
attribute named like <tt>backend-alias-&lt;alias&gt;</tt> to an AsciiDoc backend
name. For example, the following backend alias attribute definitions
appear in the <tt>[attributes]</tt> section of the global <tt>asciidoc.conf</tt>
configuration file:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>backend-alias-html=xhtml11
backend-alias-docbook=docbook45</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X100">4.2. Backend Plugins</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="4.2. Backend Plugins";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <tt>asciidoc(1)</tt> <tt>--backend</tt> option is also used to install and manage
backend plugins. A backend plugin is a ZIP file containing backend
configuration files and associated stylesheets and JavaScript files.</p>
</div>
<ul class="">
<li>
<span>
A backend plugin is used just like the built-in backends.
</span>
</li>
<li>
<span>
Backend plugins <a href="#X27">take precedence</a> over built-in backends with
  the same name.
</span>
</li>
<li>
<span>
You can use the <tt>{asciidoc-confdir}</tt> <a href="#X60">intrinsic attribute</a> to
  refer to built-in backend configuration file paths from backend
  plugin configuration files.
</span>
</li>
<li>
<span>
By default backends plugins are installed in
  <tt>$HOME/.asciidoc/backends/&lt;backend&gt;</tt> where <tt>&lt;backend&gt;</tt> is that
  backend name.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_docbook">5. DocBook</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="5. DocBook";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc generates <em>article</em>, <em>book</em> and <em>refentry</em>
<a href="http://www.docbook.org/">DocBook</a> documents (corresponding to the
AsciiDoc <em>article</em>, <em>book</em> and <em>manpage</em> document types).</p>
</div>
<div class="paragraph">
<p>Most Linux distributions come with conversion tools (collectively
called a toolchain) for <a href="#X12">converting DocBook files</a> to
presentation formats such as Postscript, HTML, PDF, EPUB, DVI,
PostScript, LaTeX, roff (the native man page format), HTMLHelp,
JavaHelp and text.  There are also programs that allow you to view
DocBook files directly, for example <a href="http://live.gnome.org/Yelp">Yelp</a>
(the GNOME help viewer).</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X12">5.1. Converting DocBook to other file formats</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="5.1. Converting DocBook to other file formats";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>DocBook files are validated, parsed and translated various
presentation file formats using a combination of applications
collectively called a DocBook <em>tool chain</em>. The function of a tool
chain is to read the DocBook markup (produced by AsciiDoc) and
transform it to a presentation format (for example HTML, PDF, HTML
Help, EPUB, DVI, PostScript, LaTeX).</p>
</div>
<div class="paragraph">
<p>A wide range of user output format requirements coupled with a choice
of available tools and stylesheets results in many valid tool chain
combinations.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X43">5.2. a2x Toolchain Wrapper</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="5.2. a2x Toolchain Wrapper";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>One of the biggest hurdles for new users is installing, configuring
and using a DocBook XML toolchain. <tt>a2x(1)</tt> can help&#8201;&#8212;&#8201;it&#8217;s a
toolchain wrapper command that will generate XHTML (chunked and
unchunked), PDF, EPUB, DVI, PS, LaTeX, man page, HTML Help and text
file outputs from an AsciiDoc text file.  <tt>a2x(1)</tt> does all the grunt
work associated with generating and sequencing the toolchain commands
and managing intermediate and output files.  <tt>a2x(1)</tt> also optionally
deploys admonition and navigation icons and a CSS stylesheet. See the
<tt>a2x(1)</tt> man page for more details. In addition to <tt>asciidoc(1)</tt> you
also need <a href="#X40">xsltproc(1)</a>, <a href="#X13">DocBook XSL Stylesheets</a> and
optionally: <a href="#X31">dblatex</a> or <a href="#X14">FOP</a> (to generate PDF);
<tt>w3m(1)</tt> or <tt>lynx(1)</tt> (to generate text).</p>
</div>
<div class="paragraph">
<p>The following examples generate <tt>doc/source-highlight-filter.pdf</tt> from
the AsciiDoc <tt>doc/source-highlight-filter.txt</tt> source file. The first
example uses <tt>dblatex(1)</tt> (the default PDF generator) the second
example forces FOP to be used:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ a2x -f pdf doc/source-highlight-filter.txt
$ a2x -f pdf --fop doc/source-highlight-filter.txt</tt></pre>
</div></div>
<div class="paragraph">
<p>See the <tt>a2x(1)</tt> man page for details.</p>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/tip.png" alt="Tip" />
</td>
<td class="content">Use the <tt>--verbose</tt> command-line option to view executed
toolchain commands.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_html_generation">5.3. HTML generation</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="5.3. HTML generation";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc produces nicely styled HTML directly without requiring a
DocBook toolchain but there are also advantages in going the DocBook
route:</p>
</div>
<ul class="">
<li>
<span>
HTML from DocBook can optionally include automatically generated
  indexes, tables of contents, footnotes, lists of figures and tables.
</span>
</li>
<li>
<span>
DocBook toolchains can also (optionally) generate separate (chunked)
  linked HTML pages for each document section.
</span>
</li>
<li>
<span>
Toolchain processing performs link and document validity checks.
</span>
</li>
<li>
<span>
If the DocBook <em>lang</em> attribute is set then things like table of
  contents, figure and table captions and admonition captions will be
  output in the specified language (setting the AsciiDoc <em>lang</em>
  attribute sets the DocBook <em>lang</em> attribute).
</span>
</li>
</ul>
<div class="paragraph">
<p>On the other hand, HTML output directly from AsciiDoc is much faster,
is easily customized and can be used in situations where there is no
suitable DocBook toolchain (for example, see the <a href="http://www.methods.co.nz/asciidoc/">AsciiDoc
website</a>).</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_pdf_generation">5.4. PDF generation</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="5.4. PDF generation";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>There are two commonly used tools to generate PDFs from DocBook,
<a href="#X31">dblatex</a> and <a href="#X14">FOP</a>.</p>
</div>
<div class="title">dblatex or FOP?</div><ul class="">
<li>
<span>
<em>dblatex</em> is easier to install, there&#8217;s zero configuration
  required and no Java VM to install&#8201;&#8212;&#8201;it just works out of the box.
</span>
</li>
<li>
<span>
<em>dblatex</em> source code highlighting and numbering is superb.
</span>
</li>
<li>
<span>
<em>dblatex</em> is easier to use as it converts DocBook directly to PDF
  whereas before using <em>FOP</em> you have to convert DocBook to XML-FO
  using <a href="#X13">DocBook XSL Stylesheets</a>.
</span>
</li>
<li>
<span>
<em>FOP</em> is more feature complete (for example, callouts are processed
  inside literal layouts) and arguably produces nicer looking output.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_html_help_generation">5.5. HTML Help generation</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="5.5. HTML Help generation";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<ol class="arabic">
<li>
<span>
Convert DocBook XML documents to HTML Help compiler source files
  using <a href="#X13">DocBook XSL Stylesheets</a> and <a href="#X40">xsltproc(1)</a>.
</span>
</li>
<li>
<span>
Convert the HTML Help source (<tt>.hhp</tt> and <tt>.html</tt>) files to HTML Help
  (<tt>.chm</tt>) files using the <a href="#X67">Microsoft HTML Help Compiler</a>.
</span>
</li>
</ol>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_toolchain_components_summary">5.6. Toolchain components summary</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="5.6. Toolchain components summary";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="dlist"><dl class="">
<dt class="hdlist1">
AsciiDoc
</dt>
<dd>
<p>
    Converts AsciiDoc (<tt>.txt</tt>) files to DocBook XML (<tt>.xml</tt>) files.
</p>
</dd>
<dt class="hdlist1">
<a id="X13"></a><a href="http://docbook.sourceforge.net/projects/xsl/">DocBook XSL Stylesheets</a>
</dt>
<dd>
<p>
  These are a set of XSL stylesheets containing rules for converting
  DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files.
  The stylesheets are used in conjunction with an XML parser such as
  <a href="#X40">xsltproc(1)</a>.
</p>
</dd>
<dt class="hdlist1">
<a id="X40"></a><a href="http://www.xmlsoft.org">xsltproc</a>
</dt>
<dd>
<p>
  An XML parser for applying XSLT stylesheets (in our case the
  <a href="#X13">DocBook XSL Stylesheets</a>) to XML documents.
</p>
</dd>
<dt class="hdlist1">
<a id="X31"></a><a href="http://dblatex.sourceforge.net/">dblatex</a>
</dt>
<dd>
<p>
  Generates PDF, DVI, PostScript and LaTeX formats directly from
  DocBook source via the intermediate LaTeX typesetting language&#8201;&#8212;&#8201;  uses <a href="#X13">DocBook XSL Stylesheets</a>, <a href="#X40">xsltproc(1)</a> and
  <tt>latex(1)</tt>.
</p>
</dd>
<dt class="hdlist1">
<a id="X14"></a><a href="http://xml.apache.org/fop/">FOP</a>
</dt>
<dd>
<p>
  The Apache Formatting Objects Processor converts XSL-FO (<tt>.fo</tt>)
  files to PDF files.  The XSL-FO files are generated from DocBook
  source files using <a href="#X13">DocBook XSL Stylesheets</a> and
  <a href="#X40">xsltproc(1)</a>.
</p>
</dd>
<dt class="hdlist1">
<a id="X67"></a>Microsoft Help Compiler
</dt>
<dd>
<p>
  The Microsoft HTML Help Compiler (<tt>hhc.exe</tt>) is a command-line tool
  that converts HTML Help source files to a single HTML Help (<tt>.chm</tt>)
  file. It runs on MS Windows platforms and can be downloaded from
  <a href="http://www.microsoft.com">http://www.microsoft.com</a>.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_asciidoc_dblatex_configuration_files">5.7. AsciiDoc dblatex configuration files</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="5.7. AsciiDoc dblatex configuration files";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The AsciiDoc distribution <tt>./dblatex</tt> directory contains
<tt>asciidoc-dblatex.xsl</tt> (customized XSL parameter settings) and
<tt>asciidoc-dblatex.sty</tt> (customized LaTeX settings). These are examples
of optional <a href="#X31">dblatex</a> output customization and are used by
<a href="#X43"><tt>a2x(1)</tt></a>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_asciidoc_docbook_xsl_stylesheets_drivers">5.8. AsciiDoc DocBook XSL Stylesheets drivers</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="5.8. AsciiDoc DocBook XSL Stylesheets drivers";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>You will have noticed that the distributed HTML and HTML Help
documentation files (for example <tt>./doc/asciidoc.html</tt>) are not the
plain outputs produced using the default <em>DocBook XSL Stylesheets</em>
configuration.  This is because they have been processed using
customized DocBook XSL Stylesheets along with (in the case of HTML
outputs) the custom <tt>./stylesheets/docbook-xsl.css</tt> CSS stylesheet.</p>
</div>
<div class="paragraph">
<p>You&#8217;ll find the customized DocBook XSL drivers along with additional
documentation in the distribution <tt>./docbook-xsl</tt> directory. The
examples that follow are executed from the distribution documentation
(<tt>./doc</tt>) directory. These drivers are also used by <a href="#X43"><tt>a2x(1)</tt></a>.</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
<tt>common.xsl</tt>
</dt>
<dd>
<p>
    Shared driver parameters.  This file is not used directly but is
    included in all the following drivers.
</p>
</dd>
<dt class="hdlist1">
<tt>chunked.xsl</tt>
</dt>
<dd>
<p>
    Generate chunked XHTML (separate HTML pages for each document
    section) in the <tt>./doc/chunked</tt> directory. For example:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>$ python ../asciidoc.py -b docbook asciidoc.txt
$ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
<tt>epub.xsl</tt>
</dt>
<dd>
<p>
    Used by <a href="#X43"><tt>a2x(1)</tt></a> to generate EPUB formatted documents.
</p>
</dd>
<dt class="hdlist1">
<tt>fo.xsl</tt>
</dt>
<dd>
<p>
    Generate XSL Formatting Object (<tt>.fo</tt>) files for subsequent PDF
    file generation using FOP. For example:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>$ python ../asciidoc.py -b docbook article.txt
$ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml &gt; article.fo
$ fop article.fo article.pdf</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
<tt>htmlhelp.xsl</tt>
</dt>
<dd>
<p>
    Generate Microsoft HTML Help source files for the MS HTML Help
    Compiler in the <tt>./doc/htmlhelp</tt> directory. This example is run on
    MS Windows from a Cygwin shell prompt:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>$ python ../asciidoc.py -b docbook asciidoc.txt
$ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml
$ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
<tt>manpage.xsl</tt>
</dt>
<dd>
<p>
    Generate a <tt>roff(1)</tt> format UNIX man page from a DocBook XML
    <em>refentry</em> document. This example generates an <tt>asciidoc.1</tt> man
    page file:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>$ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt
$ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
<tt>xhtml.xsl</tt>
</dt>
<dd>
<p>
    Convert a DocBook XML file to a single XHTML file. For example:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>$ python ../asciidoc.py -b docbook asciidoc.txt
$ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml &gt; asciidoc.html</tt></pre>
</div></div>
</dd>
</dl></div>
<div class="paragraph">
<p>If you want to see how the complete documentation set is processed
take a look at the A-A-P script <tt>./doc/main.aap</tt>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_generating_plain_text_files">6. Generating Plain Text Files</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="6. Generating Plain Text Files";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc does not have a text backend (for most purposes AsciiDoc
source text is fine), however you can convert AsciiDoc text files to
formatted text using the AsciiDoc <a href="#X43"><tt>a2x(1)</tt></a> toolchain wrapper
utility.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X35">7. HTML5 and XHTML 1.1</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="7. HTML5 and XHTML 1.1";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <em>xhtml11</em> and <em>html5</em> backends embed or link CSS and JavaScript
files in their outputs, there is also a <a href="#X99">themes</a> plugin
framework.</p>
</div>
<ul class="">
<li>
<span>
If the AsciiDoc <em>linkcss</em> attribute is defined then CSS and
  JavaScript files are linked to the output document, otherwise they
  are embedded (the default behavior).
</span>
</li>
<li>
<span>
The default locations for CSS and JavaScript files can be changed by
  setting the AsciiDoc <em>stylesdir</em> and <em>scriptsdir</em> attributes
  respectively.
</span>
</li>
<li>
<span>
The default locations for embedded and linked files differ and are
  calculated at different times&#8201;&#8212;&#8201;embedded files are loaded when
  <tt>asciidoc(1)</tt> generates the output document, linked files are loaded
  by the browser when the user views the output document.
</span>
</li>
<li>
<span>
Embedded files are automatically inserted in the output files but
  you need to manually copy linked CSS and Javascript files from
  AsciiDoc <a href="#X27">configuration directories</a> to the correct location
  relative to the output document.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
width="100%"
frame="hsides"
cellspacing="0" cellpadding="4">
<caption class="title">Table 1. Stylesheet file locations</caption>
<col width="33%" />
<col width="33%" />
<col width="33%" />
<thead>
<tr>
<th align="left" valign="top"><em>stylesdir</em> attribute</th>
<th align="left" valign="top">Linked location (<em>linkcss</em> attribute defined)</th>
<th align="left" valign="top">Embedded location (<em>linkcss</em> attribute undefined)</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">Undefined (default).</p></td>
<td align="left" valign="top"><p class="table">Same directory as the output document.</p></td>
<td align="left" valign="top"><p class="table"><tt>stylesheets</tt> subdirectory in the AsciiDoc configuration directory
(the directory containing the backend conf file).</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Absolute or relative directory name.</p></td>
<td align="left" valign="top"><p class="table">Absolute or relative to the output document.</p></td>
<td align="left" valign="top"><p class="table">Absolute or relative to the AsciiDoc configuration directory (the
directory containing the backend conf file).</p></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
width="100%"
frame="hsides"
cellspacing="0" cellpadding="4">
<caption class="title">Table 2. JavaScript file locations</caption>
<col width="33%" />
<col width="33%" />
<col width="33%" />
<thead>
<tr>
<th align="left" valign="top"><em>scriptsdir</em> attribute</th>
<th align="left" valign="top">Linked location (<em>linkcss</em> attribute defined)</th>
<th align="left" valign="top">Embedded location (<em>linkcss</em> attribute undefined)</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">Undefined (default).</p></td>
<td align="left" valign="top"><p class="table">Same directory as the output document.</p></td>
<td align="left" valign="top"><p class="table"><tt>javascripts</tt> subdirectory in the AsciiDoc configuration directory
(the directory containing the backend conf file).</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Absolute or relative directory name.</p></td>
<td align="left" valign="top"><p class="table">Absolute or relative to the output document.</p></td>
<td align="left" valign="top"><p class="table">Absolute or relative to the AsciiDoc configuration directory (the
directory containing the backend conf file).</p></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X99">7.1. Themes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="7.1. Themes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The AsciiDoc <em>theme</em> attribute is used to select an alternative CSS
stylesheet and to optionally include additional JavaScript code.</p>
</div>
<ul class="">
<li>
<span>
Theme files reside in an AsciiDoc <a href="#X27">configuration directory</a>
  named <tt>themes/&lt;theme&gt;/</tt> (where <tt>&lt;theme&gt;</tt> is the the theme name set
  by the <em>theme</em> attribute). <tt>asciidoc(1)</tt> sets the <em>themedir</em> attribute
  to the theme directory path name.
</span>
</li>
<li>
<span>
Themes can be installed, listed and removed using the <tt>asciidoc(1)</tt>
  <tt>--theme</tt> option.
</span>
</li>
<li>
<span>
AsciiDoc ships with two themes: <em>flask</em> and <em>volnitsky</em>.
</span>
</li>
<li>
<span>
The <tt>&lt;theme&gt;.css</tt> file replaces the default <tt>asciidoc.css</tt> CSS file.
</span>
</li>
<li>
<span>
The <tt>&lt;theme&gt;.js</tt> file is included in addition to the default
  <tt>asciidoc.js</tt> JavaScript file.
</span>
</li>
<li>
<span>
If the <a href="#X66">data-uri</a> attribute is defined then icons are loaded
  from the theme&#8217;s <tt>icons</tt> sub-directory if it exists (i.e.  the
  <em>iconsdir</em> attribute is set to that location).
</span>
</li>
<li>
<span>
Embedded theme files are automatically inserted in the output files
  but you need to manually copy linked CSS and Javascript files to the
  location of the output documents.
</span>
</li>
<li>
<span>
Linked CSS and JavaScript theme files are linked to the same linked
  locations as <a href="#X35">other CSS and JavaScript files</a>.
</span>
</li>
</ul>
<div class="paragraph">
<p>For example, the command-line option <tt>-a theme=foo</tt> will cause
<tt>asciidoc(1)</tt> to search <a href="#X27">well known configuration file locations</a>
for a sub-directory called <tt>themes/foo</tt> containing the stylesheet
<tt>foo.css</tt> and optionally a JavaScript file name <tt>foo.js</tt>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_document_structure">8. Document Structure</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="8. Document Structure";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>An AsciiDoc document consists of a series of <a href="#X8">block elements</a>
starting with an optional document Header, followed by an optional
Preamble, followed by zero or more document Sections.</p>
</div>
<div class="paragraph">
<p>Almost any combination of zero or more elements constitutes a valid
AsciiDoc document: documents can range from a single sentence to a
multi-part book.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_block_elements">8.1. Block Elements</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="8.1. Block Elements";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Block elements consist of one or more lines of text and may contain
other block elements.</p>
</div>
<div class="paragraph">
<p>The AsciiDoc block structure can be informally summarized as follows
<script type="text/javascript">/*<![CDATA[*/slidefootnotes += "<div class='footnote'>[1] : This is a rough structural guide, not a rigorous syntax
definition</div>" ;/*]]>*/</script>
[1]:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>Document      ::= (Header?,Preamble?,Section*)
Header        ::= (Title,(AuthorInfo,RevisionInfo?)?)
AuthorInfo    ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
RevisionInfo  ::= (RevisionNumber?,RevisionDate,RevisionRemark?)
Preamble      ::= (SectionBody)
Section       ::= (Title,SectionBody?,(Section)*)
SectionBody   ::= ((BlockTitle?,Block)|BlockMacro)+
Block         ::= (Paragraph|DelimitedBlock|List|Table)
List          ::= (BulletedList|NumberedList|LabeledList|CalloutList)
BulletedList  ::= (ListItem)+
NumberedList  ::= (ListItem)+
CalloutList   ::= (ListItem)+
LabeledList   ::= (ListEntry)+
ListEntry     ::= (ListLabel,ListItem)
ListLabel     ::= (ListTerm+)
ListItem      ::= (ItemText,(List|ListParagraph|ListContinuation)*)</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Where:</p>
</div>
<ul class="">
<li>
<span>
<em>?</em> implies zero or one occurrence, <em>+</em> implies one or more
  occurrences, <em>*</em> implies zero or more occurrences.
</span>
</li>
<li>
<span>
All block elements are separated by line boundaries.
</span>
</li>
<li>
<span>
<tt>BlockId</tt>, <tt>AttributeEntry</tt> and <tt>AttributeList</tt> block elements (not
  shown) can occur almost anywhere.
</span>
</li>
<li>
<span>
There are a number of document type and backend specific
  restrictions imposed on the block syntax.
</span>
</li>
<li>
<span>
The following elements cannot contain blank lines: Header, Title,
  Paragraph, ItemText.
</span>
</li>
<li>
<span>
A ListParagraph is a Paragraph with its <em>listelement</em> option set.
</span>
</li>
<li>
<span>
A ListContinuation is a <a href="#X15">list continuation element</a>.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X95">8.2. Header</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="8.2. Header";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The Header contains document meta-data, typically title plus optional
authorship and revision information:</p>
</div>
<ul class="">
<li>
<span>
The Header is optional, but if it is used it must start with a
  document <a href="#X17">title</a>.
</span>
</li>
<li>
<span>
Optional Author and Revision information immediately follows the
  header title.
</span>
</li>
<li>
<span>
The document header must be separated from the remainder of the
  document by one or more blank lines and cannot contain blank lines.
</span>
</li>
<li>
<span>
The header can include comments.
</span>
</li>
<li>
<span>
The header can include <a href="#X18">attribute entries</a>, typically
  <em>doctype</em>, <em>lang</em>, <em>encoding</em>, <em>icons</em>, <em>data-uri</em>, <em>toc</em>,
  <em>numbered</em>.
</span>
</li>
<li>
<span>
Header attributes are overridden by command-line attributes.
</span>
</li>
<li>
<span>
If the header contains non-UTF-8 characters then the <em>encoding</em> must
  precede the header (either in the document or on the command-line).
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Here&#8217;s an example AsciiDoc document header:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>Writing Documentation using AsciiDoc
====================================
Joe Bloggs &lt;jbloggs@mymail.com&gt;
v2.0, February 2003:
Rewritten for version 2 release.</tt></pre>
</div></div>
<div class="paragraph">
<p>The author information line contains the author&#8217;s name optionally
followed by the author&#8217;s email address. The author&#8217;s name is formatted
like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>firstname[ [middlename ]lastname][ &lt;email&gt;]]</tt></pre>
</div></div>
<div class="paragraph">
<p>i.e. a first name followed by optional middle and last names followed
by an email address in that order.  Multi-word first, middle and last
names can be entered using the underscore as a word separator.  The
email address comes last and must be enclosed in angle &lt;&gt; brackets.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Here a some examples of author information lines:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>Joe Bloggs &lt;jbloggs@mymail.com&gt;
Joe Bloggs
Vincent Willem van_Gogh</tt></pre>
</div></div>
<div class="paragraph">
<p>If the author line does not match the above specification then the
entire author line is treated as the first name.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>The optional revision information line follows the author information
line. The revision information can be one of two formats:</p>
</div>
<ol class="arabic">
<li>
<span>
An optional document revision number followed by an optional
  revision date followed by an optional revision remark:
</span>
<div class="openblock">
<div class="content">
<ul class="">
<li>
<span>
If the revision number is specified it must be followed by a
    comma.
</span>
</li>
<li>
<span>
The revision number must contain at least one numeric character.
</span>
</li>
<li>
<span>
Any non-numeric characters preceding the first numeric character
    will be dropped.
</span>
</li>
<li>
<span>
If a revision remark is specified it must be preceded by a colon.
    The revision remark extends from the colon up to the next blank
    line, attribute entry or comment and is subject to normal text
    substitutions.
</span>
</li>
<li>
<span>
If a revision number or remark has been set but the revision date
    has not been set then the revision date is set to the value of the
    <em>docdate</em> attribute.
</span>
</li>
</ul>
<div class="paragraph">
<p>Examples:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>v2.0, February 2003
February 2003
v2.0,
v2.0, February 2003: Rewritten for version 2 release.
February 2003: Rewritten for version 2 release.
v2.0,: Rewritten for version 2 release.
:Rewritten for version 2 release.</tt></pre>
</div></div>
</div></div>
</li>
<li>
<span>
The revision information line can also be an RCS/CVS/SVN $Id$
  marker:
</span>
<div class="openblock">
<div class="content">
<ul class="">
<li>
<span>
AsciiDoc extracts the <em>revnumber</em>, <em>revdate</em>, and <em>author</em>
    attributes from the $Id$ revision marker and displays them in the
    document header.
</span>
</li>
<li>
<span>
If an $Id$ revision marker is used the header author line can be
    omitted.
</span>
</li>
</ul>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$Id: mydoc.txt,v 1.5 2009/05/17 17:58:44 jbloggs Exp $</tt></pre>
</div></div>
</div></div>
</li>
</ol>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>You can override or set header parameters by passing <em>revnumber</em>,
<em>revremark</em>, <em>revdate</em>, <em>email</em>, <em>author</em>, <em>authorinitials</em>,
<em>firstname</em> and <em>lastname</em> attributes using the <tt>asciidoc(1)</tt> <tt>-a</tt>
(<tt>--attribute</tt>) command-line option. For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -a revdate=2004/07/27 article.txt</tt></pre>
</div></div>
<div class="paragraph">
<p>Attribute entries can also be added to the header for substitution in
the header template with <a href="#X18">Attribute Entry</a> elements.</p>
</div>
<div class="paragraph">
<p>The <em>title</em> element in HTML outputs is set to the AsciiDoc document
title, you can set it to a different value by including a <em>title</em>
attribute entry in the document header.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="X87">8.2.1. Additional document header information</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="8.2.1. Additional document header information";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p><em>docinfo</em> files are a mechanism for optionally including additional
meta-data in the header of the output document.</p>
</div>
<div class="paragraph">
<p>Two docinfo files are recognized: one named <tt>docinfo</tt> and a second
named like the AsciiDoc source file with a <tt>-docinfo</tt> suffix.  For
example, if the source document is called <tt>mydoc.txt</tt> then the
document information files would be <tt>docinfo.xml</tt> and
<tt>mydoc-docinfo.xml</tt> (for DocBook outputs) and <tt>docinfo.html</tt> and
<tt>mydoc-docinfo.html</tt> (for HTML outputs).</p>
</div>
<div class="paragraph">
<p>The <a href="#X97">docinfo</a> attributes control which
docinfo files are included in the output files.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>The contents docinfo file is dependent on the type of output:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
HTML
</dt>
<dd>
<p>
  Valid <em>head</em> child elements. Typically <em>style</em> and <em>script</em> elements
  for CSS and JavaScript inclusion.
</p>
</dd>
<dt class="hdlist1">
DocBook
</dt>
<dd>
<p>
  Valid <em>articleinfo</em> or <em>bookinfo</em> child elements.  DocBook defines
  numerous elements for document meta-data, for example: copyrights,
  document history and authorship information.  See the DocBook
  <tt>./doc/article-docinfo.xml</tt> example that comes with the AsciiDoc
  distribution.  The rendering of meta-data elements (or not) is
  DocBook processor dependent.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X86">8.3. Preamble</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="8.3. Preamble";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The Preamble is an optional untitled section body between the document
Header and the first Section title.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_sections">8.4. Sections</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="8.4. Sections";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>In addition to the document title (level 0), AsciiDoc supports four
section levels: 1 (top) to 4 (bottom).  Section levels are delimited
by section <a href="#X17">titles</a>.  Sections are translated using
configuration file <a href="#X93">section markup templates</a>. AsciiDoc
generates the following <a href="#X60">intrinsic attributes</a> specifically for
use in section markup templates:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
level
</dt>
<dd>
<p>
The <tt>level</tt> attribute is the section level number, it is normally just
the <a href="#X17">title</a> level number (1..4). However, if the <tt>leveloffset</tt>
attribute is defined it will be added to the <tt>level</tt> attribute. The
<tt>leveloffset</tt> attribute is useful for <a href="#X90">combining documents</a>.
</p>
</dd>
<dt class="hdlist1">
sectnum
</dt>
<dd>
<p>
The <tt>-n</tt> (<tt>--section-numbers</tt>) command-line option generates the
<tt>sectnum</tt> (section number) attribute.  The <tt>sectnum</tt> attribute is used
for section numbers in HTML outputs (DocBook section numbering are
handled automatically by the DocBook toolchain commands).
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="X93">8.4.1. Section markup templates</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="8.4.1. Section markup templates";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Section markup templates specify output markup and are defined in
AsciiDoc configuration files.  Section markup template names are
derived as follows (in order of precedence):</p>
</div>
<ol class="arabic">
<li>
<span>
From the title&#8217;s first positional attribute or <em>template</em>
   attribute. For example, the following three section titles are
   functionally equivalent:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>[[terms]]
[glossary]
List of Terms
-------------

["glossary",id="terms"]
List of Terms
-------------

[template="glossary",id="terms"]
List of Terms
-------------</tt></pre>
</div></div>
</li>
</ol>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<ol class="arabic">
<li>
<span>
When the title text matches a configuration file
   <a href="#X16"><tt>[specialsections]</tt></a> entry.
</span>
</li>
<li>
<span>
If neither of the above the default <tt>sect&lt;level&gt;</tt> template is used
   (where <tt>&lt;level&gt;</tt> is a number from 1 to 4).
</span>
</li>
</ol>
<div class="paragraph">
<p>In addition to the normal section template names (<em>sect1</em>, <em>sect2</em>,
<em>sect3</em>, <em>sect4</em>) AsciiDoc has the following templates for
frontmatter, backmatter and other special sections: <em>abstract</em>,
<em>preface</em>, <em>colophon</em>, <em>dedication</em>, <em>glossary</em>, <em>bibliography</em>,
<em>synopsis</em>, <em>appendix</em>, <em>index</em>.  These special section templates
generate the corresponding Docbook elements; for HTML outputs they
default to the <em>sect1</em> section template.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="_section_ids">8.4.2. Section IDs</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="8.4.2. Section IDs";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>If no explicit section ID is specified an ID will be synthesised from
the section title.  The primary purpose of this feature is to ensure
persistence of table of contents links (permalinks): the missing
section IDs are generated dynamically by the JavaScript TOC generator
<strong>after</strong> the page is loaded. If you link to a dynamically generated TOC
address the page will load but the browser will ignore the (as yet
ungenerated) section ID.</p>
</div>
<div class="paragraph">
<p>The IDs are generated by the following algorithm:</p>
</div>
<ul class="">
<li>
<span>
Replace all non-alphanumeric title characters with underscores.
</span>
</li>
<li>
<span>
Strip leading or trailing underscores.
</span>
</li>
<li>
<span>
Convert to lowercase.
</span>
</li>
<li>
<span>
Prepend the <tt>idprefix</tt> attribute (so there&#8217;s no possibility of name
  clashes with existing document IDs). Prepend an underscore if the
  <tt>idprefix</tt> attribute is not defined.
</span>
</li>
<li>
<span>
A numbered suffix (<tt>_2</tt>, <tt>_3</tt> &#8230;) is added if a same named
  auto-generated section ID exists.
</span>
</li>
</ul>
<div class="paragraph">
<p>For example the title <em>Jim&#8217;s House</em> would generate the ID
<tt>_jim_s_house</tt>.</p>
</div>
<div class="paragraph">
<p>Section ID synthesis can be disabled by undefining the <tt>sectids</tt>
attribute.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="X16">8.4.3. Special Section Titles</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="8.4.3. Special Section Titles";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc has a mechanism for mapping predefined section titles
auto-magically to specific markup templates. For example a title
<em>Appendix A: Code Reference</em> will automatically use the <em>appendix</em>
<a href="#X93">section markup template</a>. The mappings from title to template
name are specified in <tt>[specialsections]</tt> sections in the Asciidoc
language configuration files (<tt>lang-*.conf</tt>).  Section entries are
formatted like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>&lt;title&gt;=&lt;template&gt;</tt></pre>
</div></div>
<div class="paragraph">
<p><tt>&lt;title&gt;</tt> is a Python regular expression and <tt>&lt;template&gt;</tt> is the name
of a configuration file markup template section. If the <tt>&lt;title&gt;</tt>
matches an AsciiDoc document section title then the backend output is
marked up using the <tt>&lt;template&gt;</tt> markup template (instead of the
default <tt>sect&lt;level&gt;</tt> section template). The <tt>{title}</tt> attribute value
is set to the value of the matched regular expression group named
<em>title</em>, if there is no <em>title</em> group <tt>{title}</tt> defaults to the whole
of the AsciiDoc section title. If <tt>&lt;template&gt;</tt> is blank then any
existing entry with the same <tt>&lt;title&gt;</tt> will be deleted.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="sidebarblock">
<div class="content">
<div class="title">Special section titles vs. explicit template names</div>
<div class="paragraph">
<p>AsciiDoc has two mechanisms for specifying non-default section markup
templates: you can specify the template name explicitly (using the
<em>template</em> attribute) or indirectly (using <em>special section titles</em>).
Specifying a <a href="#X93">section template</a> attribute explicitly is
preferred.  Auto-magical <em>special section titles</em> have the following
drawbacks:</p>
</div>
<ul class="">
<li>
<span>
They are non-obvious, you have to know the exact matching
  title for each special section on a language by language basis.
</span>
</li>
<li>
<span>
Section titles are predefined and can only be customised with a
  configuration change.
</span>
</li>
<li>
<span>
The implementation is complicated by multiple languages: every
  special section title has to be defined for each language (in each
  of the <tt>lang-*.conf</tt> files).
</span>
</li>
</ul>
<div class="paragraph">
<p>Specifying special section template names explicitly does add more
noise to the source document (the <em>template</em> attribute declaration),
but the intention is obvious and the syntax is consistent with other
AsciiDoc elements c.f.  bibliographic, Q&amp;A and glossary lists.</p>
</div>
<div class="paragraph">
<p>Special section titles have been deprecated but are retained for
backward compatibility.</p>
</div>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_inline_elements">8.5. Inline Elements</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="8.5. Inline Elements";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p><a href="#X34">Inline document elements</a> are used to format text and to
perform various types of text substitution. Inline elements and inline
element syntax is defined in the <tt>asciidoc(1)</tt> configuration files.</p>
</div>
<div class="paragraph">
<p>Here is a list of AsciiDoc inline elements in the (default) order in
which they are processed:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
Special characters
</dt>
<dd>
<p>
        These character sequences escape special characters used by
        the backend markup (typically <tt>&lt;</tt>, <tt>&gt;</tt>, and <tt>&amp;</tt> characters).
        See <tt>[specialcharacters]</tt> configuration file sections.
</p>
</dd>
<dt class="hdlist1">
Quotes
</dt>
<dd>
<p>
        Elements that markup words and phrases; usually for character
        formatting. See <tt>[quotes]</tt> configuration file sections.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
Special Words
</dt>
<dd>
<p>
        Word or word phrase patterns singled out for markup without
        the need for further annotation.  See <tt>[specialwords]</tt>
        configuration file sections.
</p>
</dd>
<dt class="hdlist1">
Replacements
</dt>
<dd>
<p>
        Each replacement defines a word or word phrase pattern to
        search for along with corresponding replacement text. See
        <tt>[replacements]</tt> configuration file sections.
</p>
</dd>
<dt class="hdlist1">
Attribute references
</dt>
<dd>
<p>
        Document attribute names enclosed in braces are replaced by
        the corresponding attribute value.
</p>
</dd>
<dt class="hdlist1">
Inline Macros
</dt>
<dd>
<p>
        Inline macros are replaced by the contents of parametrized
        configuration file sections.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_document_processing">9. Document Processing</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="9. Document Processing";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The AsciiDoc source document is read and processed as follows:</p>
</div>
<ol class="arabic">
<li>
<span>
The document <em>Header</em> is parsed, header parameter values are
   substituted into the configuration file <tt>[header]</tt> template section
   which is then written to the output file.
</span>
</li>
<li>
<span>
Each document <em>Section</em> is processed and its constituent elements
   translated to the output file.
</span>
</li>
<li>
<span>
The configuration file <tt>[footer]</tt> template section is substituted
   and written to the output file.
</span>
</li>
</ol>
<div class="paragraph">
<p>When a block element is encountered <tt>asciidoc(1)</tt> determines the type of
block by checking in the following order (first to last): (section)
Titles, BlockMacros, Lists, DelimitedBlocks, Tables, AttributeEntrys,
AttributeLists, BlockTitles, Paragraphs.</p>
</div>
<div class="paragraph">
<p>The default paragraph definition <tt>[paradef-default]</tt> is last element
to be checked.</p>
</div>
<div class="paragraph">
<p>Knowing the parsing order will help you devise unambiguous macro, list
and block syntax rules.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Inline substitutions within block elements are performed in the
following default order:</p>
</div>
<ol class="arabic">
<li>
<span>
Special characters
</span>
</li>
<li>
<span>
Quotes
</span>
</li>
<li>
<span>
Special words
</span>
</li>
<li>
<span>
Replacements
</span>
</li>
<li>
<span>
Attributes
</span>
</li>
<li>
<span>
Inline Macros
</span>
</li>
<li>
<span>
Replacements2
</span>
</li>
</ol>
<div class="paragraph">
<p>The substitutions and substitution order performed on
Title, Paragraph and DelimitedBlock elements is determined by
configuration file parameters.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_text_formatting">10. Text Formatting</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="10. Text Formatting";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="X51">10.1. Quoted Text</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="10.1. Quoted Text";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Words and phrases can be formatted by enclosing inline text with
quote characters:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
<em>Emphasized text</em>
</dt>
<dd>
<p>
        Word phrases 'enclosed in single quote characters' (acute
        accents) or _underline characters_ are emphasized.
</p>
</dd>
<dt class="hdlist1">
<strong>Strong text</strong>
</dt>
<dd>
<p>
        Word phrases *enclosed in asterisk characters* are rendered
        in a strong font (usually bold).
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
<a id="X81"></a><tt>Monospaced text</tt>
</dt>
<dd>
<p>
        Word phrases +enclosed in plus characters+ are rendered in a
        monospaced font. Word phrases `enclosed in backtick
        characters` (grave accents) are also rendered in a monospaced
        font but in this case the enclosed text is rendered literally
        and is not subject to further expansion (see <a href="#X80">inline         literal passthrough</a>).
</p>
</dd>
<dt class="hdlist1">
&#8216;Single quoted text&#8217;
</dt>
<dd>
<p>
        Phrases enclosed with a `single grave accent to the left and
        a single acute accent to the right' are rendered in single
        quotation marks.
</p>
</dd>
<dt class="hdlist1">
&#8220;Double quoted text&#8221;
</dt>
<dd>
<p>
        Phrases enclosed with ``two grave accents to the left and
        two acute accents to the right'' are rendered in quotation
        marks.
</p>
</dd>
<dt class="hdlist1">
Unquoted text
</dt>
<dd>
<p>
        Placing #hashes around text# does nothing, it is a mechanism
        to allow inline attributes to be applied to otherwise
        unformatted text.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>New quote types can be defined by editing <tt>asciidoc(1)</tt> configuration
files. See the <a href="#X7">Configuration Files</a> section for details.</p>
</div>
<div class="title">Quoted text behavior</div><ul class="">
<li>
<span>
Quoting cannot be overlapped.
</span>
</li>
<li>
<span>
Different quoting types can be nested.
</span>
</li>
<li>
<span>
To suppress quoted text formatting place a backslash character
  immediately in front of the leading quote character(s). In the case
  of ambiguity between escaped and non-escaped text you will need to
  escape both leading and trailing quotes, in the case of
  multi-character quotes you may even need to escape individual
  characters.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="X96">10.1.1. Quoted text attributes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="10.1.1. Quoted text attributes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Quoted text can be prefixed with an <a href="#X21">attribute list</a>.  The first
positional attribute (<em>role</em> attribute) is translated by AsciiDoc to
an HTML <em>span</em> element <em>class</em> attribute or a DocBook <em>phrase</em> element
<em>role</em> attribute.</p>
</div>
<div class="paragraph">
<p>DocBook XSL Stylesheets translate DocBook <em>phrase</em> elements with
<em>role</em> attributes to corresponding HTML <em>span</em> elements with the same
<em>class</em> attributes; CSS can then be used
<a href="http://www.sagehill.net/docbookxsl/UsingCSS.html">to style the
generated HTML</a>.  Thus CSS styling can be applied to both DocBook and
AsciiDoc generated HTML outputs.  You can also specify multiple class
names separated by spaces.</p>
</div>
<div class="paragraph">
<p>CSS rules for text color, text background color, text size and text
decorators are included in the distributed AsciiDoc CSS files and are
used in conjunction with AsciiDoc <em>xhtml11</em>, <em>html5</em> and <em>docbook</em>
outputs. The CSS class names are:</p>
</div>
<ul class="">
<li>
<span>
<em>&lt;color&gt;</em> (text foreground color).
</span>
</li>
<li>
<span>
<em>&lt;color&gt;-background</em> (text background color).
</span>
</li>
<li>
<span>
<em>big</em> and <em>small</em> (text size).
</span>
</li>
<li>
<span>
<em>underline</em>, <em>overline</em> and <em>line-through</em> (strike through) text
  decorators.
</span>
</li>
</ul>
<div class="paragraph">
<p>Where <em>&lt;color&gt;</em> can be any of the
<a href="http://en.wikipedia.org/wiki/Web_colors#HTML_color_names">sixteen HTML
color names</a>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Examples:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[red]#Obvious# and [big red yellow-background]*very obvious*.</tt></pre>
</div></div>
<div class="literalblock">
<div class="content">
<pre><tt>[underline]#Underline text#, [overline]#overline text# and
[bold blue line-through]*bold blue and line-through*.</tt></pre>
</div></div>
<div class="paragraph">
<p>is rendered as:</p>
</div>
<div class="paragraph">
<p><span class="red">Obvious</span> and <strong><span class="big red yellow-background">very obvious</span></strong>.</p>
</div>
<div class="paragraph">
<p><span class="underline">Underline text</span>, <span class="overline">overline text</span> and
<strong><span class="bold blue line-through">bold blue and line-through</span></strong>.</p>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">Text attributes are not applicable to PDF or HTML 4 outputs.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="X52">10.1.2. Constrained and Unconstrained Quotes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="10.1.2. Constrained and Unconstrained Quotes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>There are actually two types of quotes:</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect4">
<h1 id="_constrained_quotes">10.1.2.1. Constrained quotes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect4";nexttitle="10.1.2.1. Constrained quotes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Quoted must be bounded by white space or commonly adjoining
punctuation characters. These are the most commonly used type of
quote.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect4">
<h1 id="_unconstrained_quotes">10.1.2.2. Unconstrained quotes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect4";nexttitle="10.1.2.2. Unconstrained quotes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Unconstrained quotes have no boundary constraints and can be placed
anywhere within inline text. For consistency and to make them easier
to remember unconstrained quotes are double-ups of the <tt>_</tt>, <tt>*</tt>, <tt>+</tt>
and <tt>#</tt> constrained quotes:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>__unconstrained emphasized text__
**unconstrained strong text**
++unconstrained monospaced text++
##unconstrained unquoted text##</tt></pre>
</div></div>
<div class="paragraph">
<p>The following example emboldens the letter F:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>**F**ile Open...</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_superscripts_and_subscripts">10.2. Superscripts and Subscripts</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="10.2. Superscripts and Subscripts";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Put ^carets on either^ side of the text to be superscripted, put
~tildes on either side~ of text to be subscripted.  For example, the
following line:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>e^&amp;#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^
and ~some sub text~</tt></pre>
</div></div>
<div class="paragraph">
<p>Is rendered like:</p>
</div>
<div class="paragraph">
<p>e<sup>&#960;i</sup>+1 = 0. H<sub>2</sub>O and x<sup>10</sup>. Some <sup>super text</sup>
and <sub>some sub text</sub></p>
</div>
<div class="paragraph">
<p>Superscripts and subscripts are implemented as <a href="#X52">unconstrained quotes</a> and they can be escaped with a leading backslash and prefixed
with with an attribute list.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_line_breaks">10.3. Line Breaks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="10.3. Line Breaks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>A plus character preceded by at least one space character at the end
of a non-blank line forces a line break. It generates a line break
(<tt>br</tt>) tag for HTML outputs and a custom XML <tt>asciidoc-br</tt> processing
instruction for DocBook outputs. The <tt>asciidoc-br</tt> processing
instruction is handled by <a href="#X43"><tt>a2x(1)</tt></a>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="_page_breaks">10.4. Page Breaks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="10.4. Page Breaks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>A line of three or more less-than (<tt>&lt;&lt;&lt;</tt>) characters will generate a
hard page break in DocBook and printed HTML outputs.  It uses the CSS
<tt>page-break-after</tt> property for HTML outputs and a custom XML
<tt>asciidoc-pagebreak</tt> processing instruction for DocBook outputs. The
<tt>asciidoc-pagebreak</tt> processing instruction is handled by
<a href="#X43"><tt>a2x(1)</tt></a>. Hard page breaks are sometimes handy but as a general
rule you should let your page processor generate page breaks for you.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_rulers">10.5. Rulers</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="10.5. Rulers";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>A line of three or more apostrophe characters will generate a ruler
line.  It generates a ruler (<tt>hr</tt>) tag for HTML outputs and a custom
XML <tt>asciidoc-hr</tt> processing instruction for DocBook outputs. The
<tt>asciidoc-hr</tt> processing instruction is handled by <a href="#X43"><tt>a2x(1)</tt></a>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="_tabs">10.6. Tabs</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="10.6. Tabs";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>By default tab characters input files will translated to 8 spaces. Tab
expansion is set with the <em>tabsize</em> entry in the configuration file
<tt>[miscellaneous]</tt> section and can be overridden in included files by
setting a <em>tabsize</em> attribute in the <tt>include</tt> macro&#8217;s attribute list.
For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>include::addendum.txt[tabsize=2]</tt></pre>
</div></div>
<div class="paragraph">
<p>The tab size can also be set using the attribute command-line option,
for example <tt>--attribute tabsize=4</tt></p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_replacements">10.7. Replacements</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="10.7. Replacements";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The following replacements are defined in the default AsciiDoc
configuration:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>(C) copyright, (TM) trademark, (R) registered trademark,
-- em dash, ... ellipsis, -&gt; right arrow, &lt;- left arrow, =&gt; right
double arrow, &lt;= left double arrow.</tt></pre>
</div></div>
<div class="paragraph">
<p>Which are rendered as:</p>
</div>
<div class="paragraph">
<p>&#169; copyright, &#8482; trademark, &#174; registered trademark,&#8201;&#8212;&#8201;em dash, &#8230; ellipsis, &#8594; right arrow, &#8592; left arrow, &#8658; right
double arrow, &#8656; left double arrow.</p>
</div>
<div class="paragraph">
<p>You can also include arbitrary entity references in the AsciiDoc
source. Examples:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>&amp;#x278a; &amp;#182;</tt></pre>
</div></div>
<div class="paragraph">
<p>renders:</p>
</div>
<div class="paragraph">
<p>&#x278a; &#182;</p>
</div>
<div class="paragraph">
<p>To render a replacement literally escape it with a leading back-slash.</p>
</div>
<div class="paragraph">
<p>The <a href="#X7">Configuration Files</a> section explains how to configure your
own replacements.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_special_words">10.8. Special Words</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="10.8. Special Words";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Words defined in <tt>[specialwords]</tt> configuration file sections are
automatically marked up without having to be explicitly notated.</p>
</div>
<div class="paragraph">
<p>The <a href="#X7">Configuration Files</a> section explains how to add and replace
special words.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X17">11. Titles</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="11. Titles";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Document and section titles can be in either of two formats:</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="_two_line_titles">11.1. Two line titles</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="11.1. Two line titles";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>A two line title consists of a title line, starting hard against the
left margin, and an underline. Section underlines consist a repeated
character pairs spanning the width of the preceding title (give or
take up to two characters):</p>
</div>
<div class="paragraph">
<p>The default title underlines for each of the document levels are:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>Level 0 (top level):     ======================
Level 1:                 ----------------------
Level 2:                 ~~~~~~~~~~~~~~~~~~~~~~
Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level):  ++++++++++++++++++++++</tt></pre>
</div></div>
<div class="paragraph">
<p>Examples:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>Level One Section Title
-----------------------</tt></pre>
</div></div>
<div class="literalblock">
<div class="content">
<pre><tt>Level 2 Subsection Title
~~~~~~~~~~~~~~~~~~~~~~~~</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X46">11.2. One line titles</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="11.2. One line titles";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>One line titles consist of a single line delimited on either side by
one or more equals characters (the number of equals characters
corresponds to the section level minus one).  Here are some examples:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====</tt></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">
<ul class="">
<li>
<span>
One or more spaces must fall between the title and the delimiters.
</span>
</li>
<li>
<span>
The trailing title delimiter is optional.
</span>
</li>
<li>
<span>
The one-line title syntax can be changed by editing the
  configuration file <tt>[titles]</tt> section <tt>sect0</tt>&#8230;<tt>sect4</tt> entries.
</span>
</li>
</ul>
</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_floating_titles">11.3. Floating titles</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="11.3. Floating titles";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Setting the title&#8217;s first positional attribute or <em>style</em> attribute to
<em>float</em> generates a free-floating title. A free-floating title is
rendered just like a normal section title but is not formally
associated with a text body and is not part of the regular section
hierarchy so the normal ordering rules do not apply. Floating titles
can also be used in contexts where section titles are illegal: for
example sidebar and admonition blocks.  Example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[float]
The second day
~~~~~~~~~~~~~~</tt></pre>
</div></div>
<div class="paragraph">
<p>Floating titles do not appear in a document&#8217;s table of contents.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X42">12. Block Titles</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="12. Block Titles";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>A <em>BlockTitle</em> element is a single line beginning with a period
followed by the title text. A BlockTitle is applied to the immediately
following Paragraph, DelimitedBlock, List, Table or BlockMacro. For
example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>.Notes
- Note 1.
- Note 2.</tt></pre>
</div></div>
<div class="paragraph">
<p>is rendered as:</p>
</div>
<div class="title">Notes</div><ul class="">
<li>
<span>
Note 1.
</span>
</li>
<li>
<span>
Note 2.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X41">13. BlockId Element</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="13. BlockId Element";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>A <em>BlockId</em> is a single line block element containing a unique
identifier enclosed in double square brackets. It is used to assign an
identifier to the ensuing block element. For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[[chapter-titles]]
Chapter titles can be ...</tt></pre>
</div></div>
<div class="paragraph">
<p>The preceding example identifies the ensuing paragraph so it can be
referenced from other locations, for example with
<tt>&lt;&lt;chapter-titles,chapter titles&gt;&gt;</tt>.</p>
</div>
<div class="paragraph">
<p><em>BlockId</em> elements can be applied to Title, Paragraph, List,
DelimitedBlock, Table and BlockMacro elements.  The BlockId element
sets the <tt>{id}</tt> attribute for substitution in the subsequent block&#8217;s
markup template. If a second positional argument is supplied it sets
the <tt>{reftext}</tt> attribute which is used to set the DocBook <tt>xreflabel</tt>
attribute.</p>
</div>
<div class="paragraph">
<p>The <em>BlockId</em> element has the same syntax and serves the same function
to the <a href="#X30">anchor inline macro</a>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X79">14. AttributeList Element</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="14. AttributeList Element";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>An <em>AttributeList</em> block element is an <a href="#X21">attribute list</a> on a
line by itself:</p>
</div>
<ul class="">
<li>
<span>
<em>AttributeList</em> attributes are only applied to the immediately
  following block element&#8201;&#8212;&#8201;the attributes are made available to the
  block&#8217;s markup template.
</span>
</li>
<li>
<span>
Multiple contiguous <em>AttributeList</em> elements are additively combined
  in the order they appear..
</span>
</li>
<li>
<span>
The first positional attribute in the list is often used to specify
  the ensuing element&#8217;s <a href="#X23">style</a>.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_attribute_value_substitution">14.1. Attribute value substitution</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="14.1. Attribute value substitution";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>By default, only substitutions that take place inside attribute list
values are attribute references, this is because not all attributes
are destined to be marked up and rendered as text (for example the
table <em>cols</em> attribute). To perform normal inline text substitutions
(special characters, quotes, macros, replacements) on an attribute
value you need to enclose it in single quotes. In the following quote
block the second attribute value in the AttributeList is quoted to
ensure the <em>http</em> macro is expanded to a hyperlink.</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[quote,'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]']
_____________________________________________________________________
Sir, a woman's preaching is like a dog's walking on his hind legs. It
is not done well; but you are surprised to find it done at all.
_____________________________________________________________________</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_common_attributes">14.2. Common attributes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="14.2. Common attributes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Most block elements support the following attributes:</p>
</div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="hsides"
cellspacing="0" cellpadding="4">
<col width="14%" />
<col width="14%" />
<col width="71%" />
<thead>
<tr>
<th align="left" valign="top">Name </th>
<th align="left" valign="top">Backends </th>
<th align="left" valign="top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><em>id</em></p></td>
<td align="left" valign="top"><p class="table">html4, html5, xhtml11, docbook</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Unique identifier typically serve as link targets.
Can also be set by the <em>BlockId</em> element.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>role</em></p></td>
<td align="left" valign="top"><p class="table">html4, html5, xhtml11, docbook</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Role contains a string used to classify or subclassify an element and
can be applied to AsciiDoc block elements.  The AsciiDoc <em>role</em>
attribute is translated to the <em>role</em> attribute in DocBook outputs and
is included in the <em>class</em> attribute in HTML outputs, in this respect
it behaves like the <a href="#X96">quoted text role attribute</a>.</p>
</div>
<div class="paragraph">
<p>DocBook XSL Stylesheets translate DocBook <em>role</em> attributes to HTML
<em>class</em> attributes; CSS can then be used
<a href="http://www.sagehill.net/docbookxsl/UsingCSS.html">to style the
generated HTML</a>.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>reftext</em></p></td>
<td align="left" valign="top"><p class="table">docbook</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p><em>reftext</em> is used to set the DocBook <em>xreflabel</em> attribute.
The <em>reftext</em> attribute can an also be set by the <em>BlockId</em> element.</p>
</div></div></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_paragraphs">15. Paragraphs</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="15. Paragraphs";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Paragraphs are blocks of text terminated by a blank line, the end of
file, or the start of a delimited block or a list.  There are three
paragraph syntaxes: normal, indented (literal) and admonition which
are rendered, by default, with the corresponding paragraph style. Each
syntax has a default style, but you can, if you wish,  explicitly
apply any paragraph style to any paragraph syntax.  The common
paragraph styles are <em>normal</em>, <em>literal</em>, <em>verse</em>, <em>quote</em>, <em>listing</em>,
<em>TIP</em>, <em>NOTE</em>, <em>IMPORTANT</em>, <em>WARNING</em> and <em>CAUTION</em>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_normal_paragraph_syntax">15.1. normal paragraph syntax</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="15.1. normal paragraph syntax";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Normal paragraph syntax consists of one or more non-blank lines of
text. The first line must start hard against the left margin (no
intervening white space). The default processing expectation is that
of a normal paragraph of text.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X85">15.2. literal paragraph syntax</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="15.2. literal paragraph syntax";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Literal paragraphs are rendered verbatim in a monospaced font without
any distinguishing background or border.  By default there is no text
formatting or substitutions within Literal paragraphs apart from
Special Characters and Callouts.</p>
</div>
<div class="paragraph">
<p>The <em>literal</em> style is applied implicitly to indented paragraphs i.e.
where the first line of the paragraph is indented by one or more space
or tab characters.  For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>  Consul *necessitatibus* per id,
  consetetur, eu pro everti postulant
  homero verear ea mea, qui.</tt></pre>
</div></div>
<div class="paragraph">
<p>Renders:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">Because <a href="#X64">lists</a> can be indented it&#8217;s possible for your
indented paragraph to be misinterpreted as a list&#8201;&#8212;&#8201;in situations
like this apply the <em>literal</em> style to a normal paragraph.</td>
</tr></table>
</div>
<div class="paragraph">
<p>Instead of using a paragraph indent you could apply the <em>literal</em>
style explicitly, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[literal]
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.</tt></pre>
</div></div>
<div class="paragraph">
<p>Renders:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X94">15.3. quote and verse paragraph styles</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="15.3. quote and verse paragraph styles";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The optional <em>attribution</em> and <em>citetitle</em> attributes (positional
attributes 2 and 3) specify the author and source respectively.</p>
</div>
<div class="paragraph">
<p>The <em>verse</em> style retains the line breaks, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[verse, William Blake, from Auguries of Innocence]
To see a world in a grain of sand,
And a heaven in a wild flower,
Hold infinity in the palm of your hand,
And eternity in an hour.</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Which is rendered as:</p>
</div>
<div class="verseblock">
<pre class="content">To see a world in a grain of sand,
And a heaven in a wild flower,
Hold infinity in the palm of your hand,
And eternity in an hour.</pre>
<div class="attribution">
<em>from Auguries of Innocence</em><br />
&#8212; William Blake
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>The <em>quote</em> style flows the text at left and right margins, for
example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[quote, Bertrand Russell, The World of Mathematics (1956)]
A good notation has subtlety and suggestiveness which at times makes
it almost seem like a live teacher.</tt></pre>
</div></div>
<div class="paragraph">
<p>Which is rendered as:</p>
</div>
<div class="quoteblock">
<div class="content">A good notation has subtlety and suggestiveness which at times makes
it almost seem like a live teacher.</div>
<div class="attribution">
<em>The World of Mathematics (1956)</em><br />
&#8212; Bertrand Russell
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X28">15.4. Admonition Paragraphs</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="15.4. Admonition Paragraphs";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p><em>TIP</em>, <em>NOTE</em>, <em>IMPORTANT</em>, <em>WARNING</em> and <em>CAUTION</em> admonishment
paragraph styles are generated by placing <tt>NOTE:</tt>, <tt>TIP:</tt>,
<tt>IMPORTANT:</tt>, <tt>WARNING:</tt> or <tt>CAUTION:</tt> as the first word of the
paragraph. For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>NOTE: This is an example note.</tt></pre>
</div></div>
<div class="paragraph">
<p>Alternatively, you can specify the paragraph admonition style
explicitly using an <a href="#X79">AttributeList element</a>. For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[NOTE]
This is an example note.</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Renders:</p>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">This is an example note.</td>
</tr></table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/tip.png" alt="Tip" />
</td>
<td class="content">If your admonition requires more than a single paragraph use an
<a href="#X22">admonition block</a> instead.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="X47">15.4.1. Admonition Icons and Captions</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="15.4.1. Admonition Icons and Captions";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">Admonition customization with <tt>icons</tt>, <tt>iconsdir</tt>, <tt>icon</tt> and
<tt>caption</tt> attributes does not apply when generating DocBook output. If
you are going the DocBook route then the <a href="#X43"><tt>a2x(1)</tt></a> <tt>--no-icons</tt>
and <tt>--icons-dir</tt> options can be used to set the appropriate XSL
Stylesheets parameters.</td>
</tr></table>
</div>
<div class="paragraph">
<p>By default the <tt>asciidoc(1)</tt> HTML backends generate text captions
instead of admonition icon image links. To generate links to icon
images define the <a href="#X45"><tt>icons</tt></a> attribute, for example using the <tt>-a
icons</tt> command-line option.</p>
</div>
<div class="paragraph">
<p>The <a href="#X44"><tt>iconsdir</tt></a> attribute sets the location of linked icon
images.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>You can override the default icon image using the <tt>icon</tt> attribute to
specify the path of the linked image. For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[icon="./images/icons/wink.png"]
NOTE: What lovely war.</tt></pre>
</div></div>
<div class="paragraph">
<p>Use the <tt>caption</tt> attribute to customize the admonition captions (not
applicable to <tt>docbook</tt> backend). The following example suppresses the
icon image and customizes the caption of a <em>NOTE</em> admonition
(undefining the <tt>icons</tt> attribute with <tt>icons=None</tt> is only necessary
if <a href="#X45">admonition icons</a> have been enabled):</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[icons=None, caption="My Special Note"]
NOTE: This is my special note.</tt></pre>
</div></div>
<div class="paragraph">
<p>This subsection also applies to <a href="#X22">Admonition Blocks</a>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_delimited_blocks">16. Delimited Blocks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="16. Delimited Blocks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Delimited blocks are blocks of text enveloped by leading and trailing
delimiter lines (normally a series of four or more repeated
characters). The behavior of Delimited Blocks is specified by entries
in configuration file <tt>[blockdef-*]</tt> sections.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="_predefined_delimited_blocks">16.1. Predefined Delimited Blocks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="16.1. Predefined Delimited Blocks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc ships with a number of predefined DelimitedBlocks (see the
<tt>asciidoc.conf</tt> configuration file in the <tt>asciidoc(1)</tt> program
directory):</p>
</div>
<div class="paragraph">
<p>Predefined delimited block underlines:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>CommentBlock:     //////////////////////////
PassthroughBlock: ++++++++++++++++++++++++++
ListingBlock:     --------------------------
LiteralBlock:     ..........................
SidebarBlock:     **************************
QuoteBlock:       __________________________
ExampleBlock:     ==========================
OpenBlock:        --</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
frame="hsides"
cellspacing="0" cellpadding="4">
<caption class="title">Table 3. Default DelimitedBlock substitutions</caption>
<col />
<col />
<col />
<col />
<col />
<col />
<col />
<col />
<thead>
<tr>
<th align="left" valign="top"> </th>
<th align="center" valign="top">Attributes </th>
<th align="center" valign="top">Callouts </th>
<th align="center" valign="top">Macros </th>
<th align="center" valign="top"> Quotes </th>
<th align="center" valign="top">Replacements</th>
<th align="center" valign="top">Special chars </th>
<th align="center" valign="top">Special words</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><em>PassthroughBlock</em></p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>ListingBlock</em></p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>LiteralBlock</em></p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>SidebarBlock</em></p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>QuoteBlock</em></p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>ExampleBlock</em></p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>OpenBlock</em></p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">No</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
<td align="center" valign="top"><p class="table">Yes</p></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_listing_blocks">16.2. Listing Blocks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="16.2. Listing Blocks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p><em>ListingBlocks</em> are rendered verbatim in a monospaced font, they
retain line and whitespace formatting and are often distinguished by a
background or border. There is no text formatting or substitutions
within Listing blocks apart from Special Characters and Callouts.
Listing blocks are often used for computer output and file listings.</p>
</div>
<div class="paragraph">
<p>Here&#8217;s an example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>--------------------------------------
#include &lt;stdio.h&gt;

int main() {
   printf("Hello World!\n");
   exit(0);
}
--------------------------------------</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Which will be rendered like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>#include &lt;stdio.h&gt;

int main() {
    printf("Hello World!\n");
    exit(0);
}</tt></pre>
</div></div>
<div class="paragraph">
<p>By convention <a href="#X59">filter blocks</a> use the listing block syntax and
are implemented as distinct listing block styles.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X65">16.3. Literal Blocks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="16.3. Literal Blocks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p><em>LiteralBlocks</em> are rendered just like <a href="#X85">literal paragraphs</a>.
Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>...................................
Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.
...................................</tt></pre>
</div></div>
<div class="paragraph">
<p>Renders:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>Consul *necessitatibus* per id,
consetetur, eu pro everti postulant
homero verear ea mea, qui.</tt></pre>
</div></div>
<div class="paragraph">
<p>If the <em>listing</em> style is applied to a LiteralBlock it will be
rendered as a ListingBlock (this is handy if you have a listing
containing a ListingBlock).</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_sidebar_blocks">16.4. Sidebar Blocks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="16.4. Sidebar Blocks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>A sidebar is a short piece of text presented outside the narrative
flow of the main text. The sidebar is normally presented inside a
bordered box to set it apart from the main text.</p>
</div>
<div class="paragraph">
<p>The sidebar body is treated like a normal section body.</p>
</div>
<div class="paragraph">
<p>Here&#8217;s an example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>.An Example Sidebar
************************************************
Any AsciiDoc SectionBody element (apart from
SidebarBlocks) can be placed inside a sidebar.
************************************************</tt></pre>
</div></div>
<div class="paragraph">
<p>Which will be rendered like:</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="title">An Example Sidebar</div>
<div class="paragraph">
<p>Any AsciiDoc SectionBody element (apart from
SidebarBlocks) can be placed inside a sidebar.</p>
</div>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X26">16.5. Comment Blocks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="16.5. Comment Blocks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The contents of <em>CommentBlocks</em> are not processed; they are useful for
annotations and for excluding new or outdated content that you don&#8217;t
want displayed. CommentBlocks are never written to output files.
Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>//////////////////////////////////////////
CommentBlock contents are not processed by
asciidoc(1).
//////////////////////////////////////////</tt></pre>
</div></div>
<div class="paragraph">
<p>See also <a href="#X25">Comment Lines</a>.</p>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">System macros are executed inside comment blocks.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X76">16.6. Passthrough Blocks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="16.6. Passthrough Blocks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>By default the block contents is subject only to <em>attributes</em> and
<em>macros</em> substitutions (use an explicit <em>subs</em> attribute to apply
different substitutions).  PassthroughBlock content will often be
backend specific. Here&#8217;s an example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[subs="quotes"]
++++++++++++++++++++++++++++++++++++++
&lt;table border="1"&gt;&lt;tr&gt;
  &lt;td&gt;*Cell 1*&lt;/td&gt;
  &lt;td&gt;*Cell 2*&lt;/td&gt;
&lt;/tr&gt;&lt;/table&gt;
++++++++++++++++++++++++++++++++++++++</tt></pre>
</div></div>
<div class="paragraph">
<p>The following styles can be applied to passthrough blocks:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
pass
</dt>
<dd>
<p>
  No substitutions are performed. This is equivalent to <tt>subs="none"</tt>.
</p>
</dd>
<dt class="hdlist1">
asciimath, latexmath
</dt>
<dd>
<p>
  By default no substitutions are performed, the contents are rendered
  as <a href="#X78">mathematical formulas</a>.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_quote_blocks">16.7. Quote Blocks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="16.7. Quote Blocks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p><em>QuoteBlocks</em> are used for quoted passages of text. There are two
styles: <em>quote</em> and <em>verse</em>. The style behavior is identical to
<a href="#X94">quote and verse paragraphs</a> except that blocks can contain
multiple paragraphs and, in the case of the <em>quote</em> style, other
section elements.  The first positional attribute sets the style, if
no attributes are specified the <em>quote</em> style is used.  The optional
<em>attribution</em> and <em>citetitle</em> attributes (positional attributes 2 and
3) specify the quote&#8217;s author and source. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes]
____________________________________________________________________
As he spoke there was the sharp sound of horses' hoofs and
grating wheels against the curb, followed by a sharp pull at the
bell. Holmes whistled.

"A pair, by the sound," said he. "Yes," he continued, glancing
out of the window. "A nice little brougham and a pair of
beauties. A hundred and fifty guineas apiece. There's money in
this case, Watson, if there is nothing else."
____________________________________________________________________</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Which is rendered as:</p>
</div>
<div class="quoteblock">
<div class="content">
<div class="paragraph">
<p>As he spoke there was the sharp sound of horses' hoofs and
grating wheels against the curb, followed by a sharp pull at the
bell. Holmes whistled.</p>
</div>
<div class="paragraph">
<p>"A pair, by the sound," said he. "Yes," he continued, glancing
out of the window. "A nice little brougham and a pair of
beauties. A hundred and fifty guineas apiece. There&#8217;s money in
this case, Watson, if there is nothing else."</p>
</div>
</div>
<div class="attribution">
<em>The Adventures of Sherlock Holmes</em><br />
&#8212; Sir Arthur Conan Doyle
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X48">16.8. Example Blocks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="16.8. Example Blocks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p><em>ExampleBlocks</em> encapsulate the DocBook Example element and are used
for, well, examples.  Example blocks can be titled by preceding them
with a <em>BlockTitle</em>.  DocBook toolchains will normally automatically
number examples and generate a <em>List of Examples</em> backmatter section.</p>
</div>
<div class="paragraph">
<p>Example blocks are delimited by lines of equals characters and can
contain any block elements apart from Titles, BlockTitles and
Sidebars) inside an example block. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>.An example
=====================================================================
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.
=====================================================================</tt></pre>
</div></div>
<div class="paragraph">
<p>Renders:</p>
</div>
<div class="exampleblock">
<div class="title">Example 1. An example</div>
<div class="content">
<div class="paragraph">
<p>Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.</p>
</div>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>A title prefix that can be inserted with the <tt>caption</tt> attribute
(HTML backends). For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[caption="Example 1: "]
.An example with a custom caption
=====================================================================
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.
=====================================================================</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X22">16.9. Admonition Blocks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="16.9. Admonition Blocks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <em>ExampleBlock</em> definition includes a set of admonition
<a href="#X23">styles</a> (<em>NOTE</em>, <em>TIP</em>, <em>IMPORTANT</em>, <em>WARNING</em>, <em>CAUTION</em>) for
generating admonition blocks (admonitions containing more than a
<a href="#X28">single paragraph</a>).  Just precede the <em>ExampleBlock</em> with an
attribute list specifying the admonition style name. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[NOTE]
.A NOTE admonition block
=====================================================================
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.

. Fusce euismod commodo velit.
. Vivamus fringilla mi eu lacus.
  .. Fusce euismod commodo velit.
  .. Vivamus fringilla mi eu lacus.
. Donec eget arcu bibendum
  nunc consequat lobortis.
=====================================================================</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Renders:</p>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">
<div class="title">A NOTE admonition block</div>
<div class="paragraph">
<p>Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.</p>
</div>
<ol class="arabic">
<li>
<span>
Fusce euismod commodo velit.
</span>
</li>
<li>
<span>
Vivamus fringilla mi eu lacus.
</span>
<ol class="loweralpha">
<li>
<span>
Fusce euismod commodo velit.
</span>
</li>
<li>
<span>
Vivamus fringilla mi eu lacus.
</span>
</li>
</ol>
</li>
<li>
<span>
Donec eget arcu bibendum
  nunc consequat lobortis.
</span>
</li>
</ol>
</td>
</tr></table>
</div>
<div class="paragraph">
<p>See also <a href="#X47">Admonition Icons and Captions</a>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X29">16.10. Open Blocks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="16.10. Open Blocks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>An <em>OpenBlock</em> groups a set of block elements. <em>OpenBlock</em> usage:</p>
</div>
<ol class="arabic">
<li>
<span>
<a href="#X15">List item continuation</a>.
</span>
</li>
<li>
<span>
Apply the <em>abstract</em> style to generate an abstract, for example:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>[abstract]
--
In this paper we will ...
--</tt></pre>
</div></div>
</li>
<li>
<span>
Apply the <em>partintro</em> style to generate a book part introduction for
  a multi-part book, for example:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>[partintro]
.Optional part introduction title
--
Optional part introduction goes here.
--</tt></pre>
</div></div>
</li>
</ol>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X64">17. Lists</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="17. Lists";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="title">List types</div><ul class="">
<li>
<span>
Bulleted lists. Also known as itemized or unordered lists.
</span>
</li>
<li>
<span>
Numbered lists. Also called ordered lists.
</span>
</li>
<li>
<span>
Labeled lists. Sometimes called variable or definition lists.
</span>
</li>
<li>
<span>
Callout lists (a list of callout annotations).
</span>
</li>
</ul>
<div class="title">List behavior</div><ul class="">
<li>
<span>
List item indentation is optional and does not determine nesting,
  indentation does however make the source more readable.
</span>
</li>
<li>
<span>
Another list or a literal paragraph immediately following a list
  item will be implicitly included in the list item; use <a href="#X15">list   item continuation</a> to explicitly append other block elements to a
  list item.
</span>
</li>
<li>
<span>
A comment block or a comment line block macro element will terminate
  a list&#8201;&#8212;&#8201;use inline comment lines to put comments inside lists.
</span>
</li>
<li>
<span>
The <tt>listindex</tt> <a href="#X60">intrinsic attribute</a> is the current list item
  index (1..). If this attribute is used outside a list then it&#8217;s value
  is the number of items in the most recently closed list. Useful for
  displaying the number of items in a list.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_bulleted_lists">17.1. Bulleted Lists</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="17.1. Bulleted Lists";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Bulleted list items start with a single dash or one to five asterisks
followed by some white space then some text. Bulleted list syntaxes
are:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>- List item.
* List item.
** List item.
*** List item.
**** List item.
***** List item.</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_numbered_lists">17.2. Numbered Lists</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="17.2. Numbered Lists";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>List item numbers are explicit or implicit.</p>
</div>
<div class="paragraph"><div class="title">Explicit numbering</div>
<p>List items begin with a number followed by some white space then the
item text. The numbers can be decimal (arabic), roman (upper or lower
case) or alpha (upper or lower case). Decimal and alpha numbers are
terminated with a period, roman numbers are terminated with a closing
parenthesis. The different terminators are necessary to ensure <em>i</em>,
<em>v</em> and <em>x</em> roman numbers are are distinguishable from <em>x</em>, <em>v</em> and
<em>x</em> alpha numbers. Examples:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>1.   Arabic (decimal) numbered list item.
a.   Lower case alpha (letter) numbered list item.
F.   Upper case alpha (letter) numbered list item.
iii) Lower case roman numbered list item.
IX)  Upper case roman numbered list item.</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph"><div class="title">Implicit numbering</div>
<p>List items begin one to five period characters, followed by some white
space then the item text. Examples:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>. Arabic (decimal) numbered list item.
.. Lower case alpha (letter) numbered list item.
... Lower case roman numbered list item.
.... Upper case alpha (letter) numbered list item.
..... Upper case roman numbered list item.</tt></pre>
</div></div>
<div class="paragraph">
<p>You can use the <em>style</em> attribute (also the first positional
attribute) to specify an alternative numbering style.  The numbered
list style can be one of the following values: <em>arabic</em>, <em>loweralpha</em>,
<em>upperalpha</em>, <em>lowerroman</em>, <em>upperroman</em>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Here are some examples of bulleted and numbered lists:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>- Praesent eget purus quis magna eleifend eleifend.
  1. Fusce euismod commodo velit.
    a. Fusce euismod commodo velit.
    b. Vivamus fringilla mi eu lacus.
    c. Donec eget arcu bibendum nunc consequat lobortis.
  2. Vivamus fringilla mi eu lacus.
    i)  Fusce euismod commodo velit.
    ii) Vivamus fringilla mi eu lacus.
  3. Donec eget arcu bibendum nunc consequat lobortis.
  4. Nam fermentum mattis ante.
- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  * Fusce euismod commodo velit.
  ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
     adolescens. Sit munere ponderum dignissim et. Minim luptatum et
     vel.
  ** Vivamus fringilla mi eu lacus.
  * Donec eget arcu bibendum nunc consequat lobortis.
- Nulla porttitor vulputate libero.
  . Fusce euismod commodo velit.
  . Vivamus fringilla mi eu lacus.
[upperroman]
    .. Fusce euismod commodo velit.
    .. Vivamus fringilla mi eu lacus.
  . Donec eget arcu bibendum nunc consequat lobortis.</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Which render as:</p>
</div>
<ul class="">
<li>
<span>
Praesent eget purus quis magna eleifend eleifend.
</span>
<ol class="arabic">
<li>
<span>
Fusce euismod commodo velit.
</span>
<ol class="loweralpha">
<li>
<span>
Fusce euismod commodo velit.
</span>
</li>
<li>
<span>
Vivamus fringilla mi eu lacus.
</span>
</li>
<li>
<span>
Donec eget arcu bibendum nunc consequat lobortis.
</span>
</li>
</ol>
</li>
<li>
<span>
Vivamus fringilla mi eu lacus.
</span>
<ol class="lowerroman">
<li>
<span>
Fusce euismod commodo velit.
</span>
</li>
<li>
<span>
Vivamus fringilla mi eu lacus.
</span>
</li>
</ol>
</li>
<li>
<span>
Donec eget arcu bibendum nunc consequat lobortis.
</span>
</li>
<li>
<span>
Nam fermentum mattis ante.
</span>
</li>
</ol>
</li>
<li>
<span>
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
</span>
<ul class="">
<li>
<span>
Fusce euismod commodo velit.
</span>
<ul class="">
<li>
<span>
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
     adolescens. Sit munere ponderum dignissim et. Minim luptatum et
     vel.
</span>
</li>
<li>
<span>
Vivamus fringilla mi eu lacus.
</span>
</li>
</ul>
</li>
<li>
<span>
Donec eget arcu bibendum nunc consequat lobortis.
</span>
</li>
</ul>
</li>
<li>
<span>
Nulla porttitor vulputate libero.
</span>
<ol class="arabic">
<li>
<span>
Fusce euismod commodo velit.
</span>
</li>
<li>
<span>
Vivamus fringilla mi eu lacus.
</span>
<ol class="upperroman">
<li>
<span>
Fusce euismod commodo velit.
</span>
</li>
<li>
<span>
Vivamus fringilla mi eu lacus.
</span>
</li>
</ol>
</li>
<li>
<span>
Donec eget arcu bibendum nunc consequat lobortis.
</span>
</li>
</ol>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>A predefined <em>compact</em> option is available to bulleted and numbered
lists&#8201;&#8212;&#8201;this translates to the DocBook <em>spacing="compact"</em> lists
attribute which may or may not be processed by the DocBook toolchain.
Example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[options="compact"]
- Compact list item.
- Another compact list item.</tt></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/tip.png" alt="Tip" />
</td>
<td class="content">To apply the <em>compact</em> option globally define a document-wide
<em>compact-option</em> attribute, e.g. using the <tt>-a compact-option</tt>
command-line option.</td>
</tr></table>
</div>
<div class="paragraph">
<p>You can set the list start number using the <em>start</em> attribute (works
for HTML outputs and DocBook outputs processed by DocBook XSL
Stylesheets). Example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[start=7]
. List item 7.
. List item 8.</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_labeled_lists">17.3. Labeled Lists</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="17.3. Labeled Lists";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Labeled list items consist of one or more text labels followed by the
text of the list item.</p>
</div>
<div class="paragraph">
<p>An item label begins a line with an alphanumeric character hard
against the left margin and ends with two, three or four colons or two
semi-colons. A list item can have multiple labels, one per line.</p>
</div>
<div class="paragraph">
<p>The list item text consists of one or more lines of text starting
after the last label (either on the same line or a new line) and can
be followed by nested List or ListParagraph elements. Item text can be
optionally indented.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Here are some examples:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>In::
Lorem::
  Fusce euismod commodo velit.

  Fusce euismod commodo velit.

Ipsum:: Vivamus fringilla mi eu lacus.
  * Vivamus fringilla mi eu lacus.
  * Donec eget arcu bibendum nunc consequat lobortis.
Dolor::
  Donec eget arcu bibendum nunc consequat lobortis.
  Suspendisse;;
    A massa id sem aliquam auctor.
  Morbi;;
    Pretium nulla vel lorem.
  In;;
    Dictum mauris in urna.
    Vivamus::: Fringilla mi eu lacus.
    Donec:::   Eget arcu bibendum nunc consequat lobortis.</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Which render as:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
In
</dt>
<dt class="hdlist1">
Lorem
</dt>
<dd>
<p>
  Fusce euismod commodo velit.
</p>
<div class="literalblock">
<div class="content">
<pre><tt>Fusce euismod commodo velit.</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
Ipsum
</dt>
<dd>
<p>
Vivamus fringilla mi eu lacus.
</p>
<ul class="">
<li>
<span>
Vivamus fringilla mi eu lacus.
</span>
</li>
<li>
<span>
Donec eget arcu bibendum nunc consequat lobortis.
</span>
</li>
</ul>
</dd>
<dt class="hdlist1">
Dolor
</dt>
<dd>
<p>
  Donec eget arcu bibendum nunc consequat lobortis.
</p>
<div class="dlist"><dl class="">
<dt class="hdlist1">
Suspendisse
</dt>
<dd>
<p>
    A massa id sem aliquam auctor.
</p>
</dd>
<dt class="hdlist1">
Morbi
</dt>
<dd>
<p>
    Pretium nulla vel lorem.
</p>
</dd>
<dt class="hdlist1">
In
</dt>
<dd>
<p>
    Dictum mauris in urna.
</p>
<div class="dlist"><dl class="">
<dt class="hdlist1">
Vivamus
</dt>
<dd>
<p>
Fringilla mi eu lacus.
</p>
</dd>
<dt class="hdlist1">
Donec
</dt>
<dd>
<p>
Eget arcu bibendum nunc consequat lobortis.
</p>
</dd>
</dl></div>
</dd>
</dl></div>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="_horizontal_labeled_list_style">17.3.1. Horizontal labeled list style</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="17.3.1. Horizontal labeled list style";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <em>horizontal</em> labeled list style (also the first positional
attribute) places the list text side-by-side with the label instead of
under the label. Here is an example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[horizontal]
*Lorem*:: Fusce euismod commodo velit.  Qui in magna commodo, est
labitur dolorum an. Est ne magna primis adolescens.

  Fusce euismod commodo velit.

*Ipsum*:: Vivamus fringilla mi eu lacus.
- Vivamus fringilla mi eu lacus.
- Donec eget arcu bibendum nunc consequat lobortis.

*Dolor*::
  - Vivamus fringilla mi eu lacus.
  - Donec eget arcu bibendum nunc consequat lobortis.</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Which render as:</p>
</div>
<div class="hdlist"><table>
<tr>
<td class="hdlist1">
<strong>Lorem</strong>
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Fusce euismod commodo velit.  Qui in magna commodo, est
labitur dolorum an. Est ne magna primis adolescens.
</p>
<div class="literalblock">
<div class="content">
<pre><tt>Fusce euismod commodo velit.</tt></pre>
</div></div>
</td>
</tr>
<tr>
<td class="hdlist1">
<strong>Ipsum</strong>
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
Vivamus fringilla mi eu lacus.
</p>
<ul class="">
<li>
<span>
Vivamus fringilla mi eu lacus.
</span>
</li>
<li>
<span>
Donec eget arcu bibendum nunc consequat lobortis.
</span>
</li>
</ul>
</td>
</tr>
<tr>
<td class="hdlist1">
<strong>Dolor</strong>
<br />
</td>
<td class="hdlist2">
<ul class="">
<li>
<span>
Vivamus fringilla mi eu lacus.
</span>
</li>
<li>
<span>
Donec eget arcu bibendum nunc consequat lobortis.
</span>
</li>
</ul>
</td>
</tr>
</table></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">
<ul class="">
<li>
<span>
Current PDF toolchains do not make a good job of determining
  the relative column widths for horizontal labeled lists.
</span>
</li>
<li>
<span>
Nested horizontal labeled lists will generate DocBook validation
  errors because the <em>DocBook XML V4.2</em> DTD does not permit nested
  informal tables (although <a href="#X13">DocBook XSL Stylesheets</a> and
  <a href="#X31">dblatex</a> process them correctly).
</span>
</li>
<li>
<span>
The label width can be set as a percentage of the total width by
  setting the <em>width</em> attribute e.g. <tt>width="10%"</tt>
</span>
</li>
</ul>
</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_question_and_answer_lists">17.4. Question and Answer Lists</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="17.4. Question and Answer Lists";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc comes pre-configured with a <em>qanda</em> style labeled list for generating
DocBook question and answer (Q&amp;A) lists. Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[qanda]
Question one::
        Answer one.
Question two::
        Answer two.</tt></pre>
</div></div>
<div class="paragraph">
<p>Renders:</p>
</div>
<div class="qlist qanda"><ol>
<li>
<p><em>
Question one
</em></p>
<p>
        Answer one.
</p>
</li>
<li>
<p><em>
Question two
</em></p>
<p>
        Answer two.
</p>
</li>
</ol></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_glossary_lists">17.5. Glossary Lists</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="17.5. Glossary Lists";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc comes pre-configured with a <em>glossary</em> style labeled list for
generating DocBook glossary lists. Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[glossary]
A glossary term::
    The corresponding definition.
A second glossary term::
    The corresponding definition.</tt></pre>
</div></div>
<div class="paragraph">
<p>For working examples see the <tt>article.txt</tt> and <tt>book.txt</tt> documents in
the AsciiDoc <tt>./doc</tt> distribution directory.</p>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">To generate valid DocBook output glossary lists must be located
in a section that uses the <em>glossary</em> <a href="#X93">section markup template</a>.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_bibliography_lists">17.6. Bibliography Lists</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="17.6. Bibliography Lists";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc comes with a predefined <em>bibliography</em> bulleted list style
generating DocBook bibliography entries. Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[bibliography]
.Optional list title
- [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX
  Programming'. Addison-Wesley. ISBN 0-13-142901-9.
- [[[walsh-muellner]]] Norman Walsh &amp; Leonard Muellner.
  'DocBook - The Definitive Guide'. O'Reilly &amp; Associates.
  1999. ISBN 1-56592-580-7.</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>The <tt>[[[&lt;reference&gt;]]]</tt> syntax is a bibliography entry anchor, it
generates an anchor named <tt>&lt;reference&gt;</tt> and additionally displays
<tt>[&lt;reference&gt;]</tt> at the anchor position. For example <tt>[[[taoup]]]</tt>
generates an anchor named <tt>taoup</tt> that displays <tt>[taoup]</tt> at the
anchor position. Cite the reference from elsewhere your document using
<tt>&lt;&lt;taoup&gt;&gt;</tt>, this displays a hyperlink (<tt>[taoup]</tt>) to the
corresponding bibliography entry anchor.</p>
</div>
<div class="paragraph">
<p>For working examples see the <tt>article.txt</tt> and <tt>book.txt</tt> documents in
the AsciiDoc <tt>./doc</tt> distribution directory.</p>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">To generate valid DocBook output bibliography lists must be
located in a <a href="#X93">bibliography section</a>.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X15">17.7. List Item Continuation</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="17.7. List Item Continuation";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Another list or a literal paragraph immediately following a list item
is implicitly appended to the list item; to append other block
elements to a list item you need to explicitly join them to the list
item with a <em>list continuation</em> (a separator line containing a single
plus character). Multiple block elements can be appended to a list
item using list continuations (provided they are legal list item
children in the backend markup).</p>
</div>
<div class="paragraph">
<p>Here are some examples of list item continuations: list item one
contains multiple continuations; list item two is continued with an
<a href="#X29">OpenBlock</a> containing multiple elements:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item continued with a third paragraph.

2. List item two continued with an open block.
+
--
This paragraph is part of the preceding list item.

a. This list is nested and does not require explicit item continuation.
+
This paragraph is part of the preceding list item.

b. List item b.

This paragraph belongs to item two of the outer list.
--</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Renders:</p>
</div>
<ol class="arabic">
<li>
<span>
List item one.
</span>
<div class="paragraph">
<p>List item one continued with a second paragraph followed by an
Indented block.</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ ls *.sh
$ mv *.sh ~/tmp</tt></pre>
</div></div>
<div class="paragraph">
<p>List item continued with a third paragraph.</p>
</div>
</li>
<li>
<span>
List item two continued with an open block.
</span>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>This paragraph is part of the preceding list item.</p>
</div>
<ol class="loweralpha">
<li>
<span>
This list is nested and does not require explicit item continuation.
</span>
<div class="paragraph">
<p>This paragraph is part of the preceding list item.</p>
</div>
</li>
<li>
<span>
List item b.
</span>
</li>
</ol>
<div class="paragraph">
<p>This paragraph belongs to item two of the outer list.</p>
</div>
</div></div>
</li>
</ol>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X92">18. Footnotes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="18. Footnotes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The shipped AsciiDoc configuration includes three footnote inline
macros:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
<tt>footnote:[&lt;text&gt;]</tt>
</dt>
<dd>
<p>
  Generates a footnote with text <tt>&lt;text&gt;</tt>.
</p>
</dd>
<dt class="hdlist1">
<tt>footnoteref:[&lt;id&gt;,&lt;text&gt;]</tt>
</dt>
<dd>
<p>
  Generates a footnote with a reference ID <tt>&lt;id&gt;</tt> and text <tt>&lt;text&gt;</tt>.
</p>
</dd>
<dt class="hdlist1">
<tt>footnoteref:[&lt;id&gt;]</tt>
</dt>
<dd>
<p>
  Generates a reference to the footnote with ID <tt>&lt;id&gt;</tt>.
</p>
</dd>
</dl></div>
<div class="paragraph">
<p>The footnote text can span multiple lines.</p>
</div>
<div class="paragraph">
<p>The <em>xhtml11</em> and <em>html5</em> backends render footnotes dynamically using
JavaScript; <em>html4</em> outputs do not use JavaScript and leave the
footnotes inline; <em>docbook</em> footnotes are processed by the downstream
DocBook toolchain.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Example footnotes:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>A footnote footnote:[An example footnote.];
a second footnote with a reference ID footnoteref:[note2,Second footnote.];
finally a reference to the second footnote footnoteref:[note2].</tt></pre>
</div></div>
<div class="paragraph">
<p>Renders:</p>
</div>
<div class="paragraph">
<p>A footnote <script type="text/javascript">/*<![CDATA[*/slidefootnotes += "<div class='footnote'>[2] : An example footnote.</div>" ;/*]]>*/</script>
[2];
a second footnote with a reference ID <script type="text/javascript">/*<![CDATA[*/slidefootnotes += "<div class='footnote'>[note2] : Second footnote.</div>" ;/*]]>*/</script>
[note2];
finally a reference to the second footnote [note2].</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_indexes">19. Indexes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="19. Indexes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The shipped AsciiDoc configuration includes the inline macros for
generating DocBook index entries.</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
<tt>indexterm:[&lt;primary&gt;,&lt;secondary&gt;,&lt;tertiary&gt;]</tt>
</dt>
<dt class="hdlist1">
<tt>(((&lt;primary&gt;,&lt;secondary&gt;,&lt;tertiary&gt;)))</tt>
</dt>
<dd>
<p>
    This inline macro generates an index term (the <tt>&lt;secondary&gt;</tt> and
    <tt>&lt;tertiary&gt;</tt> positional attributes are optional). Example:
    <tt>indexterm:[Tigers,Big cats]</tt> (or, using the alternative syntax
    <tt>(((Tigers,Big cats)))</tt>.  Index terms that have secondary and
    tertiary entries also generate separate index terms for the
    secondary and tertiary entries. The index terms appear in the
    index, not the primary text flow.
</p>
</dd>
<dt class="hdlist1">
<tt>indexterm2:[&lt;primary&gt;]</tt>
</dt>
<dt class="hdlist1">
<tt>((&lt;primary&gt;))</tt>
</dt>
<dd>
<p>
    This inline macro generates an index term that appears in both the
    index and the primary text flow.  The <tt>&lt;primary&gt;</tt> should not be
    padded to the left or right with white space characters.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>For working examples see the <tt>article.txt</tt> and <tt>book.txt</tt> documents in
the AsciiDoc <tt>./doc</tt> distribution directory.</p>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">Index entries only really make sense if you are generating
DocBook markup&#8201;&#8212;&#8201;DocBook conversion programs automatically generate
an index at the point an <em>Index</em> section appears in source document.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_callouts">20. Callouts</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="20. Callouts";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Callouts are a mechanism for annotating verbatim text (for example:
source code, computer output and user input). Callout markers are
placed inside the annotated text while the actual annotations are
presented in a callout list after the annotated text. Here&#8217;s an
example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt> .MS-DOS directory listing
 -----------------------------------------------------
 10/17/97   9:04         &lt;DIR&gt;    bin
 10/16/97  14:11         &lt;DIR&gt;    DOS            &lt;1&gt;
 10/16/97  14:40         &lt;DIR&gt;    Program Files
 10/16/97  14:46         &lt;DIR&gt;    TEMP
 10/17/97   9:04         &lt;DIR&gt;    tmp
 10/16/97  14:37         &lt;DIR&gt;    WINNT
 10/16/97  14:25             119  AUTOEXEC.BAT   &lt;2&gt;
  2/13/94   6:21          54,619  COMMAND.COM    &lt;2&gt;
 10/16/97  14:25             115  CONFIG.SYS     &lt;2&gt;
 11/16/97  17:17      61,865,984  pagefile.sys
  2/13/94   6:21           9,349  WINA20.386     &lt;3&gt;
 -----------------------------------------------------

 &lt;1&gt; This directory holds MS-DOS.
 &lt;2&gt; System startup code for DOS.
 &lt;3&gt; Some sort of Windows 3.1 hack.</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Which renders:</p>
</div>
<div class="listingblock">
<div class="title">MS-DOS directory listing</div>
<div class="content">
<pre><tt>10/17/97   9:04         &lt;DIR&gt;    bin
10/16/97  14:11         &lt;DIR&gt;    DOS            <object data="../images/icons/callouts/1.svg" type="image/svg+xml" title="1" width="4%">
<img src="../images/icons/callouts/1.png" alt="1" />
</object>
10/16/97  14:40         &lt;DIR&gt;    Program Files
10/16/97  14:46         &lt;DIR&gt;    TEMP
10/17/97   9:04         &lt;DIR&gt;    tmp
10/16/97  14:37         &lt;DIR&gt;    WINNT
10/16/97  14:25             119  AUTOEXEC.BAT   <object data="../images/icons/callouts/2.svg" type="image/svg+xml" title="2" width="4%">
<img src="../images/icons/callouts/2.png" alt="2" />
</object>
 2/13/94   6:21          54,619  COMMAND.COM    <object data="../images/icons/callouts/2.svg" type="image/svg+xml" title="2" width="4%">
<img src="../images/icons/callouts/2.png" alt="2" />
</object>
10/16/97  14:25             115  CONFIG.SYS     <object data="../images/icons/callouts/2.svg" type="image/svg+xml" title="2" width="4%">
<img src="../images/icons/callouts/2.png" alt="2" />
</object>
11/16/97  17:17      61,865,984  pagefile.sys
 2/13/94   6:21           9,349  WINA20.386     <object data="../images/icons/callouts/3.svg" type="image/svg+xml" title="3" width="4%">
<img src="../images/icons/callouts/3.png" alt="3" />
</object></tt></pre>
</div></div>
<div class="colist arabic"><table><tbody>
<tr><td><object data="../images/icons/callouts/1.svg" type="image/svg+xml" title="1" width="4%"><img src="../images/icons/callouts/1.png" alt="1" /></object></td><td style="vertical-align: middle;">
This directory holds MS-DOS.
</td></tr>
<tr><td><object data="../images/icons/callouts/2.svg" type="image/svg+xml" title="2" width="4%"><img src="../images/icons/callouts/2.png" alt="2" /></object></td><td style="vertical-align: middle;">
System startup code for DOS.
</td></tr>
<tr><td><object data="../images/icons/callouts/3.svg" type="image/svg+xml" title="3" width="4%"><img src="../images/icons/callouts/3.png" alt="3" /></object></td><td style="vertical-align: middle;">
Some sort of Windows 3.1 hack.
</td></tr>
</tbody></table></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="title">Explanation</div><ul class="">
<li>
<span>
The callout marks are whole numbers enclosed in angle brackets&#8201;&#8212;&#8201;  they refer to the correspondingly numbered item in the following
  callout list.
</span>
</li>
<li>
<span>
By default callout marks are confined to <em>LiteralParagraphs</em>,
  <em>LiteralBlocks</em> and <em>ListingBlocks</em> (although this is a
  configuration file option and can be changed).
</span>
</li>
<li>
<span>
Callout list item numbering is fairly relaxed&#8201;&#8212;&#8201;list items can
  start with <tt>&lt;n&gt;</tt>, <tt>n&gt;</tt> or <tt>&gt;</tt> where <tt>n</tt> is the optional list item
  number (in the latter case list items starting with a single <tt>&gt;</tt>
  character are implicitly numbered starting at one).
</span>
</li>
<li>
<span>
Callout lists should not be nested.
</span>
</li>
<li>
<span>
Callout lists start list items hard against the left margin.
</span>
</li>
<li>
<span>
If you want to present a number inside angle brackets you&#8217;ll need to
  escape it with a backslash to prevent it being interpreted as a
  callout mark.
</span>
</li>
</ul>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">Define the AsciiDoc <em>icons</em> attribute (for example using the <tt>-a
icons</tt> command-line option) to display callout icons.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_implementation_notes">20.1. Implementation Notes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="20.1. Implementation Notes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Callout marks are generated by the <em>callout</em> inline macro while
callout lists are generated using the <em>callout</em> list definition. The
<em>callout</em> macro and <em>callout</em> list are special in that they work
together. The <em>callout</em> inline macro is not enabled by the normal
<em>macros</em> substitutions option, instead it has its own <em>callouts</em>
substitution option.</p>
</div>
<div class="paragraph">
<p>The following attributes are available during inline callout macro
substitution:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
<tt>{index}</tt>
</dt>
<dd>
<p>
    The callout list item index inside the angle brackets.
</p>
</dd>
<dt class="hdlist1">
<tt>{coid}</tt>
</dt>
<dd>
<p>
    An identifier formatted like <tt>CO&lt;listnumber&gt;-&lt;index&gt;</tt> that
    uniquely identifies the callout mark. For example <tt>CO2-4</tt>
    identifies the fourth callout mark in the second set of callout
    marks.
</p>
</dd>
</dl></div>
<div class="paragraph">
<p>The <tt>{coids}</tt> attribute can be used during callout list item
substitution&#8201;&#8212;&#8201;it is a space delimited list of callout IDs that refer
to the explanatory list item.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_including_callouts_in_included_code">20.2. Including callouts in included code</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="20.2. Including callouts in included code";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>You can annotate working code examples with callouts&#8201;&#8212;&#8201;just remember
to put the callouts inside source code comments. This example displays
the <tt>test.py</tt> source file (containing a single callout) using the
<em>source</em> (code highlighter) filter:</p>
</div>
<div class="listingblock">
<div class="title">AsciiDoc source</div>
<div class="content">
<pre><tt> [source,python]
 -------------------------------------------
 \include::test.py[]
 -------------------------------------------

 &lt;1&gt; Print statement.</tt></pre>
</div></div>
<div class="listingblock">
<div class="title">Included <tt>test.py</tt> source</div>
<div class="content">
<pre><tt>print 'Hello World!'   # &lt;1&gt;</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_macros">21. Macros</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="21. Macros";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Macros are a mechanism for substituting parametrized text into output
documents.</p>
</div>
<div class="paragraph">
<p>Macros have a <em>name</em>, a single <em>target</em> argument and an <em>attribute
list</em>.  The usual syntax is <tt>&lt;name&gt;:&lt;target&gt;[&lt;attrlist&gt;]</tt> (for
inline macros) and <tt>&lt;name&gt;::&lt;target&gt;[&lt;attrlist&gt;]</tt> (for block
macros).  Here are some examples:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>http://www.docbook.org/[DocBook.org]
include::chapt1.txt[tabsize=2]
mailto:srackham@gmail.com[]</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="title">Macro behavior</div><ul class="">
<li>
<span>
<tt>&lt;name&gt;</tt> is the macro name. It can only contain letters, digits or
  dash characters and cannot start with a dash.
</span>
</li>
<li>
<span>
The optional <tt>&lt;target&gt;</tt> cannot contain white space characters.
</span>
</li>
<li>
<span>
<tt>&lt;attrlist&gt;</tt> is a <a href="#X21">list of attributes</a> enclosed in square
  brackets.
</span>
</li>
<li>
<span>
<tt>]</tt> characters inside attribute lists must be escaped with a
  backslash.
</span>
</li>
<li>
<span>
Expansion of macro references can normally be escaped by prefixing a
  backslash character (see the AsciiDoc <em>FAQ</em> for examples of
  exceptions to this rule).
</span>
</li>
<li>
<span>
Attribute references in block macros are expanded.
</span>
</li>
<li>
<span>
The substitutions performed prior to Inline macro macro expansion
  are determined by the inline context.
</span>
</li>
<li>
<span>
Macros are processed in the order they appear in the configuration
  file(s).
</span>
</li>
<li>
<span>
Calls to inline macros can be nested inside different inline macros
  (an inline macro call cannot contain a nested call to itself).
</span>
</li>
<li>
<span>
In addition to <tt>&lt;name&gt;</tt>, <tt>&lt;target&gt;</tt> and <tt>&lt;attrlist&gt;</tt> the
  <tt>&lt;passtext&gt;</tt> and <tt>&lt;subslist&gt;</tt> named groups are available to
  <a href="#X77">passthrough macros</a>. A macro is a passthrough macro if the
  definition includes a <tt>&lt;passtext&gt;</tt> named group.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_inline_macros">21.1. Inline Macros</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="21.1. Inline Macros";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Inline Macros occur in an inline element context. Predefined Inline
macros include <em>URLs</em>, <em>image</em> and <em>link</em> macros.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect3">
<h1 id="_urls">21.1.1. URLs</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="21.1.1. URLs";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p><em>http</em>, <em>https</em>, <em>ftp</em>, <em>file</em>, <em>mailto</em> and <em>callto</em> URLs are
rendered using predefined inline macros.</p>
</div>
<ul class="">
<li>
<span>
If you don&#8217;t need a custom link caption you can enter the <em>http</em>,
  <em>https</em>, <em>ftp</em>, <em>file</em> URLs and email addresses without any special
  macro syntax.
</span>
</li>
<li>
<span>
If the <tt>&lt;attrlist&gt;</tt> is empty the URL is displayed.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Here are some examples:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>http://www.docbook.org/[DocBook.org]
http://www.docbook.org/
mailto:joe.bloggs@foobar.com[email Joe Bloggs]
joe.bloggs@foobar.com</tt></pre>
</div></div>
<div class="paragraph">
<p>Which are rendered:</p>
</div>
<div class="paragraph">
<p><a href="http://www.docbook.org/">DocBook.org</a></p>
</div>
<div class="paragraph">
<p><a href="http://www.docbook.org/">http://www.docbook.org/</a></p>
</div>
<div class="paragraph">
<p><a href="mailto:joe.bloggs@foobar.com">email Joe Bloggs</a></p>
</div>
<div class="paragraph">
<p><a href="mailto:joe.bloggs@foobar.com">joe.bloggs@foobar.com</a></p>
</div>
<div class="paragraph">
<p>If the <tt>&lt;target&gt;</tt> necessitates space characters use <tt>%20</tt>, for example
<tt>large%20image.png</tt>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="_internal_cross_references">21.1.2. Internal Cross References</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="21.1.2. Internal Cross References";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Two AsciiDoc inline macros are provided for creating hypertext links
within an AsciiDoc document. You can use either the standard macro
syntax or the (preferred) alternative.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect4">
<h1 id="X30">21.1.2.1. anchor</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect4";nexttitle="21.1.2.1. anchor";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Used to specify hypertext link targets:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[[&lt;id&gt;,&lt;xreflabel&gt;]]
anchor:&lt;id&gt;[&lt;xreflabel&gt;]</tt></pre>
</div></div>
<div class="paragraph">
<p>The <tt>&lt;id&gt;</tt> is a unique string that conforms to the output markup&#8217;s
anchor syntax. The optional <tt>&lt;xreflabel&gt;</tt> is the text to be displayed
by captionless <em>xref</em> macros that refer to this anchor. The optional
<tt>&lt;xreflabel&gt;</tt> is only really useful when generating DocBook output.
Example anchor:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[[X1]]</tt></pre>
</div></div>
<div class="paragraph">
<p>You may have noticed that the syntax of this inline element is the
same as that of the <a href="#X41">BlockId block element</a>, this is no
coincidence since they are functionally equivalent.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect4">
<h1 id="_xref">21.1.2.2. xref</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect4";nexttitle="21.1.2.2. xref";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Creates a hypertext link to a document anchor.</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>&lt;&lt;&lt;id&gt;,&lt;caption&gt;&gt;&gt;
xref:&lt;id&gt;[&lt;caption&gt;]</tt></pre>
</div></div>
<div class="paragraph">
<p>The <tt>&lt;id&gt;</tt> refers to an anchor ID. The optional <tt>&lt;caption&gt;</tt> is the
link&#8217;s displayed text. Example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>&lt;&lt;X21,attribute lists&gt;&gt;</tt></pre>
</div></div>
<div class="paragraph">
<p>If <tt>&lt;caption&gt;</tt> is not specified then the displayed text is
auto-generated:</p>
</div>
<ul class="">
<li>
<span>
The AsciiDoc <em>xhtml11</em> and <em>html5</em> backends display the <tt>&lt;id&gt;</tt>
  enclosed in square brackets.
</span>
</li>
<li>
<span>
If DocBook is produced the DocBook toolchain is responsible for the
  displayed text which will normally be the referenced figure, table
  or section title number followed by the element&#8217;s title text.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Here is an example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[[tiger_image]]
.Tyger tyger
image::tiger.png[]

This can be seen in &lt;&lt;tiger_image&gt;&gt;.</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="_linking_to_local_documents">21.1.3. Linking to Local Documents</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="21.1.3. Linking to Local Documents";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Hypertext links to files on the local file system are specified using
the <em>link</em> inline macro.</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>link:&lt;target&gt;[&lt;caption&gt;]</tt></pre>
</div></div>
<div class="paragraph">
<p>The <em>link</em> macro generates relative URLs. The link macro <tt>&lt;target&gt;</tt> is
the target file name (relative to the file system location of the
referring document). The optional <tt>&lt;caption&gt;</tt> is the link&#8217;s displayed
text. If <tt>&lt;caption&gt;</tt> is not specified then <tt>&lt;target&gt;</tt> is displayed.
Example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>link:downloads/foo.zip[download foo.zip]</tt></pre>
</div></div>
<div class="paragraph">
<p>You can use the <tt>&lt;filename&gt;#&lt;id&gt;</tt> syntax to refer to an anchor within
a target document but this usually only makes sense when targeting
HTML documents.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="X9">21.1.4. Images</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="21.1.4. Images";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Inline images are inserted into the output document using the <em>image</em>
macro. The inline syntax is:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>image:&lt;target&gt;[&lt;attributes&gt;]</tt></pre>
</div></div>
<div class="paragraph">
<p>The contents of the image file <tt>&lt;target&gt;</tt> is displayed. To display the
image its file format must be supported by the target backend
application. HTML and DocBook applications normally support PNG or JPG
files.</p>
</div>
<div class="paragraph">
<p><tt>&lt;target&gt;</tt> file name paths are relative to the location of the
referring document.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="title">Image macro attributes</div><ul id="X55" class="">
<li>
<span>
The optional <em>alt</em> attribute is also the first positional attribute,
  it specifies alternative text which is displayed if the output
  application is unable to display the image file (see also
  <a href="http://htmlhelp.com/feature/art3.htm">Use of ALT texts in IMGs</a>). For
  example:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>image:images/logo.png[Company Logo]</tt></pre>
</div></div>
</li>
<li>
<span>
The optional <em>title</em> attribute provides a title for the image. The
  <a href="#X49">block image macro</a> renders the title alongside the image.
  The inline image macro displays the title as a popup &#8220;tooltip&#8221; in
  visual browsers (AsciiDoc HTML outputs only).
</span>
</li>
<li>
<span>
The optional <tt>width</tt> and <tt>height</tt> attributes scale the image size
  and can be used in any combination. The units are pixels.  The
  following example scales the previous example to a height of 32
  pixels:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>image:images/logo.png["Company Logo",height=32]</tt></pre>
</div></div>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="title">Image macro attributes (2)</div><ul class="">
<li>
<span>
The optional <tt>link</tt> attribute is used to link the image to an
  external document. The following example links a screenshot
  thumbnail to a full size version:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>image:screen-thumbnail.png[height=32,link="screen.png"]</tt></pre>
</div></div>
</li>
<li>
<span>
The optional <tt>scaledwidth</tt> attribute is only used in DocBook block
  images (specifically for PDF documents). The following example
  scales the images to 75% of the available print width:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>image::images/logo.png[scaledwidth="75%",alt="Company Logo"]</tt></pre>
</div></div>
</li>
<li>
<span>
The image <tt>scale</tt> attribute sets the DocBook <tt>imagedata</tt> element
  <tt>scale</tt> attribute.
</span>
</li>
<li>
<span>
The optional <tt>align</tt> attribute is used for horizontal image
  alignment.  Allowed values are <tt>center</tt>, <tt>left</tt> and <tt>right</tt>. For
  example:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>image::images/tiger.png["Tiger image",align="left"]</tt></pre>
</div></div>
</li>
<li>
<span>
The optional <tt>float</tt> attribute floats the image <tt>left</tt> or <tt>right</tt> on
  the page (works with HTML outputs only, has no effect on DocBook
  outputs). <tt>float</tt> and <tt>align</tt> attributes are mutually exclusive.
  Use the <tt>unfloat::[]</tt> block macro to stop floating.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="_comment_lines">21.1.5. Comment Lines</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="21.1.5. Comment Lines";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>See <a href="#X25">comment block macro</a>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_block_macros">21.2. Block Macros</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="21.2. Block Macros";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>A Block macro reference must be contained in a single line separated
either side by a blank line or a block delimiter.</p>
</div>
<div class="paragraph">
<p>Block macros behave just like Inline macros, with the following
differences:</p>
</div>
<ul class="">
<li>
<span>
They occur in a block context.
</span>
</li>
<li>
<span>
The default syntax is <tt>&lt;name&gt;::&lt;target&gt;[&lt;attrlist&gt;]</tt> (two
  colons, not one).
</span>
</li>
<li>
<span>
Markup template section names end in <tt>-blockmacro</tt> instead of
  <tt>-inlinemacro</tt>.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="_block_identifier">21.2.1. Block Identifier</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="21.2.1. Block Identifier";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The Block Identifier macro sets the <tt>id</tt> attribute and has the same
syntax as the <a href="#X30">anchor inline macro</a> since it performs
essentially the same function&#8201;&#8212;&#8201;block templates use the <tt>id</tt>
attribute as a block element ID. For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[[X30]]</tt></pre>
</div></div>
<div class="paragraph">
<p>This is equivalent to the <tt>[id="X30"]</tt> <a href="#X79">AttributeList element</a>).</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="X49">21.2.2. Images</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="21.2.2. Images";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <em>image</em> block macro is used to display images in a block context.
The syntax is:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>image::&lt;target&gt;[&lt;attributes&gt;]</tt></pre>
</div></div>
<div class="paragraph">
<p>The block <tt>image</tt> macro has the same <a href="#X55">macro attributes</a> as it&#8217;s
<a href="#X9">inline image macro</a> counterpart.</p>
</div>
<div class="paragraph">
<p>Block images can be titled by preceding the <em>image</em> macro with a
<em>BlockTitle</em>.  DocBook toolchains normally number titled block images
and optionally list them in an automatically generated <em>List of
Figures</em> backmatter section.</p>
</div>
<div class="paragraph">
<p>This example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>.Main circuit board
image::images/layout.png[J14P main circuit board]</tt></pre>
</div></div>
<div class="paragraph">
<p>is equivalent to:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>image::images/layout.png["J14P main circuit board",
                          title="Main circuit board"]</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>A title prefix that can be inserted with the <tt>caption</tt> attribute
(HTML backends). For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>.Main circuit board
[caption="Figure 2: "]
image::images/layout.png[J14P main circuit board]</tt></pre>
</div></div>
<div class="sidebarblock" id="X66">
<div class="content">
<div class="title">Embedding images in XHTML documents</div>
<div class="paragraph">
<p>If you define the <tt>data-uri</tt> attribute then images will be embedded in
XHTML outputs using the
<a href="http://en.wikipedia.org/wiki/Data:_URI_scheme">data URI scheme</a>.  You
can use the <em>data-uri</em> attribute with the <em>xhtml11</em> and <em>html5</em>
backends to produce single-file XHTML documents with embedded images
and CSS, for example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -a data-uri mydocument.txt</tt></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">
<ul class="">
<li>
<span>
All current popular browsers support data URIs, although versions
  of Internet Explorer prior to version 8 do not.
</span>
</li>
<li>
<span>
Some browsers limit the size of data URIs.
</span>
</li>
</ul>
</td>
</tr></table>
</div>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="X25">21.2.3. Comment Lines</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="21.2.3. Comment Lines";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Single lines starting with two forward slashes hard up against the
left margin are treated as comments. Comment lines do not appear in
the output unless the <em>showcomments</em> attribute is defined.  Comment
lines have been implemented as both block and inline macros so a
comment line can appear as a stand-alone block or within block elements
that support inline macro expansion. Example comment line:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>// This is a comment.</tt></pre>
</div></div>
<div class="paragraph">
<p>If the <em>showcomments</em> attribute is defined comment lines are written
to the output:</p>
</div>
<ul class="">
<li>
<span>
In DocBook the comment lines are enclosed by the <em>remark</em> element
  (which may or may not be rendered by your toolchain).
</span>
</li>
<li>
<span>
The <em>showcomments</em> attribute does not expose <a href="#X26">Comment Blocks</a>.
  Comment Blocks are never passed to the output.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_system_macros">21.3. System Macros</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="21.3. System Macros";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>System macros are block macros that perform a predefined task and are
hardwired into the <tt>asciidoc(1)</tt> program.</p>
</div>
<ul class="">
<li>
<span>
You can escape system macros with a leading backslash character
  (as you can with other macros).
</span>
</li>
<li>
<span>
The syntax and tasks performed by system macros is built into
  <tt>asciidoc(1)</tt> so they don&#8217;t appear in configuration files.  You can
  however customize the syntax by adding entries to a configuration
  file <tt>[macros]</tt> section.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="X63">21.3.1. Include Macros</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="21.3.1. Include Macros";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <tt>include</tt> and <tt>include1</tt>  system macros to include the contents of
a named file into the source document.</p>
</div>
<div class="paragraph">
<p>The <tt>include</tt> macro includes a file as if it were part of the parent
document&#8201;&#8212;&#8201;tabs are expanded and system macros processed. The
contents of <tt>include1</tt> files are not subject to tab expansion or
system macro processing nor are attribute or lower priority
substitutions performed. The <tt>include1</tt> macro&#8217;s intended use is to
include verbatim embedded CSS or scripts into configuration file
headers.  Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>include::chapter1.txt[tabsize=4]</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="title">Include macro behavior</div><ul class="">
<li>
<span>
If the included file name is specified with a relative path then the
  path is relative to the location of the referring document.
</span>
</li>
<li>
<span>
Include macros can appear inside configuration files.
</span>
</li>
<li>
<span>
Files included from within <em>DelimitedBlocks</em> are read to completion
  to avoid false end-of-block underline termination.
</span>
</li>
<li>
<span>
Attribute references are expanded inside the include <em>target</em>; if an
  attribute is undefined then the included file is silently skipped.
</span>
</li>
<li>
<span>
The <em>tabsize</em> macro attribute sets the number of space characters to
  be used for tab expansion in the included file (not applicable to
  <tt>include1</tt> macro).
</span>
</li>
<li>
<span>
The <em>depth</em> macro attribute sets the maximum permitted number of
  subsequent nested includes (not applicable to <tt>include1</tt> macro which
  does not process nested includes). Setting <em>depth</em> to <em>1</em> disables
  nesting inside the included file. By default, nesting is limited to
  a depth of five.
</span>
</li>
<li>
<span>
If the he <em>warnings</em> attribute is set to <em>False</em> (or any other Python
  literal that evaluates to boolean false) then no warning message is
  printed if the included file does not exist. By default <em>warnings</em>
  are enabled.
</span>
</li>
<li>
<span>
Internally the <tt>include1</tt> macro is translated to the <tt>include1</tt>
  system attribute which means it must be evaluated in a region where
  attribute substitution is enabled. To inhibit nested substitution in
  included files it is preferable to use the <tt>include</tt> macro and set
  the attribute <tt>depth=1</tt>.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="_conditional_inclusion_macros">21.3.2. Conditional Inclusion Macros</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="21.3.2. Conditional Inclusion Macros";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Lines of text in the source document can be selectively included or
excluded from processing based on the existence (or not) of a document
attribute.</p>
</div>
<div class="paragraph">
<p>Document text between the <tt>ifdef</tt> and <tt>endif</tt> macros is included if a
document attribute is defined:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>ifdef::&lt;attribute&gt;[]
:
endif::&lt;attribute&gt;[]</tt></pre>
</div></div>
<div class="paragraph">
<p>Document text between the <tt>ifndef</tt> and <tt>endif</tt> macros is not included
if a document attribute is defined:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>ifndef::&lt;attribute&gt;[]
:
endif::&lt;attribute&gt;[]</tt></pre>
</div></div>
<div class="paragraph">
<p><tt>&lt;attribute&gt;</tt> is an attribute name which is optional in the trailing
<tt>endif</tt> macro.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>If you only want to process a single line of text then the text can be
put inside the square brackets and the <tt>endif</tt> macro omitted, for
example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>ifdef::revnumber[Version number 42]</tt></pre>
</div></div>
<div class="paragraph">
<p>Is equivalent to:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>ifdef::revnumber[]
Version number 42
endif::revnumber[]</tt></pre>
</div></div>
<div class="paragraph">
<p><em>ifdef</em> and <em>ifndef</em> macros also accept multiple attribute names:</p>
</div>
<ul class="">
<li>
<span>
Multiple <em>,</em> separated attribute names evaluate to defined if one
  or more of the attributes is defined, otherwise it&#8217;s value is
  undefined.
</span>
</li>
<li>
<span>
Multiple <em>+</em> separated attribute names evaluate to defined if all
  of the attributes is defined, otherwise it&#8217;s value is undefined.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Document text between the <tt>ifeval</tt> and <tt>endif</tt> macros is included if
the Python expression inside the square brackets is true. Example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>ifeval::[{rs458}==2]
:
endif::[]</tt></pre>
</div></div>
<ul class="">
<li>
<span>
Document attribute references are expanded before the expression is
  evaluated.
</span>
</li>
<li>
<span>
If an attribute reference is undefined then the expression is
  considered false.
</span>
</li>
</ul>
<div class="paragraph">
<p>Take a look at the <tt>*.conf</tt> configuration files in the AsciiDoc
distribution for examples of conditional inclusion macro usage.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="_executable_system_macros">21.3.3. Executable system macros</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="21.3.3. Executable system macros";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <em>eval</em>, <em>sys</em> and <em>sys2</em> block macros exhibit the same behavior as
their same named <a href="#X24">system attribute references</a>. The difference
is that system macros occur in a block macro context whereas system
attributes are confined to inline contexts where attribute
substitution is enabled.</p>
</div>
<div class="paragraph">
<p>The following example displays a long directory listing inside a
literal block:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>------------------
sys::[ls -l *.txt]
------------------</tt></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">There are no block macro versions of the <em>eval3</em> and <em>sys3</em>
system attributes.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="_template_system_macro">21.3.4. Template System Macro</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="21.3.4. Template System Macro";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <tt>template</tt> block macro allows the inclusion of one configuration
file template section within another.  The following example includes
the <tt>[admonitionblock]</tt> section in the <tt>[admonitionparagraph]</tt>
section:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[admonitionparagraph]
template::[admonitionblock]</tt></pre>
</div></div>
<div class="title">Template macro behavior</div><ul class="">
<li>
<span>
The <tt>template::[]</tt> macro is useful for factoring configuration file
  markup.
</span>
</li>
<li>
<span>
<tt>template::[]</tt> macros cannot be nested.
</span>
</li>
<li>
<span>
<tt>template::[]</tt> macro expansion is applied to all sections
  after all configuration files have been read.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X77">21.4. Passthrough macros</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="21.4. Passthrough macros";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Passthrough macros are analogous to <a href="#X76">passthrough blocks</a> and are
used to pass text directly to the output. The substitution performed
on the text is determined by the macro definition but can be overridden
by the <tt>&lt;subslist&gt;</tt>.  The usual syntax is
<tt>&lt;name&gt;:&lt;subslist&gt;[&lt;passtext&gt;]</tt> (for inline macros) and
<tt>&lt;name&gt;::&lt;subslist&gt;[&lt;passtext&gt;]</tt> (for block macros). Passthroughs, by
definition, take precedence over all other text substitutions.</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
pass
</dt>
<dd>
<p>
  Inline and block. Passes text unmodified (apart from explicitly
  specified substitutions). Examples:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>pass:[&lt;q&gt;To be or not to be&lt;/q&gt;]
pass:attributes,quotes[&lt;u&gt;the '{author}'&lt;/u&gt;]</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
asciimath, latexmath
</dt>
<dd>
<p>
  Inline and block. Passes text unmodified.  Used for
  <a href="#X78">mathematical formulas</a>.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
+++
</dt>
<dd>
<p>
  Inline and block. The triple-plus passthrough is functionally
  identical to the <em>pass</em> macro but you don&#8217;t have to escape <tt>]</tt>
  characters and you can prefix with quoted attributes in the inline
  version. Example:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>Red [red]+++`sum_(i=1)\^n i=(n(n+1))/2`$+++ AsciiMathML formula</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
$$
</dt>
<dd>
<p>
  Inline and block. The double-dollar passthrough is functionally
  identical to the triple-plus passthrough with one exception: special
  characters are escaped. Example:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>$$`[[a,b],[c,d]]((n),(k))`$$</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
<a id="X80"></a>`
</dt>
<dd>
<p>
  Text quoted with single backtick characters constitutes an <em>inline
  literal</em> passthrough. The enclosed text is rendered in a monospaced
  font and is only subject to special character substitution.  This
  makes sense since monospace text is usually intended to be rendered
  literally and often contains characters that would otherwise have to
  be escaped. If you need monospaced text containing inline
  substitutions use a <a href="#X81">plus character instead of a backtick</a>.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_macro_definitions">21.5. Macro Definitions</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="21.5. Macro Definitions";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Each entry in the configuration <tt>[macros]</tt> section is a macro
definition which can take one of the following forms:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
<tt>&lt;pattern&gt;=&lt;name&gt;[&lt;subslist]</tt>
</dt>
<dd>
<p>
Inline macro definition.
</p>
</dd>
<dt class="hdlist1">
<tt>&lt;pattern&gt;=#&lt;name&gt;[&lt;subslist]</tt>
</dt>
<dd>
<p>
Block macro definition.
</p>
</dd>
<dt class="hdlist1">
<tt>&lt;pattern&gt;=+&lt;name&gt;[&lt;subslist]</tt>
</dt>
<dd>
<p>
System macro definition.
</p>
</dd>
<dt class="hdlist1">
<tt>&lt;pattern&gt;</tt>
</dt>
<dd>
<p>
Delete the existing macro with this <tt>&lt;pattern&gt;</tt>.
</p>
</dd>
</dl></div>
<div class="paragraph">
<p><tt>&lt;pattern&gt;</tt> is a Python regular expression and <tt>&lt;name&gt;</tt> is the name of
a markup template. If <tt>&lt;name&gt;</tt> is omitted then it is the value of the
regular expression match group named <em>name</em>.  The optional
<tt>[&lt;subslist]</tt> is a comma-separated list of substitution names enclosed
in <tt>[]</tt> brackets, it sets the default substitutions for passthrough
text, if omitted then no passthrough substitutions are performed.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph"><div class="title">Pattern named groups</div>
<p>The following named groups can be used in macro <tt>&lt;pattern&gt;</tt> regular
expressions and are available as markup template attributes:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
name
</dt>
<dd>
<p>
  The macro name.
</p>
</dd>
<dt class="hdlist1">
target
</dt>
<dd>
<p>
  The macro target.
</p>
</dd>
<dt class="hdlist1">
attrlist
</dt>
<dd>
<p>
  The macro attribute list.
</p>
</dd>
<dt class="hdlist1">
passtext
</dt>
<dd>
<p>
  Contents of this group are passed unmodified to the output subject
  only to <em>subslist</em> substitutions.
</p>
</dd>
<dt class="hdlist1">
subslist
</dt>
<dd>
<p>
  Processed as a comma-separated list of substitution names for
  <em>passtext</em> substitution, overrides the the macro definition
  <em>subslist</em>.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="title">Here&#8217;s what happens during macro substitution</div><ul class="">
<li>
<span>
Each contextually relevant macro <em>pattern</em> from the <tt>[macros]</tt>
  section is matched against the input source line.
</span>
</li>
<li>
<span>
If a match is found the text to be substituted is loaded from a
  configuration markup template section named like
  <tt>&lt;name&gt;-inlinemacro</tt> or <tt>&lt;name&gt;-blockmacro</tt> (depending on the macro
  type).
</span>
</li>
<li>
<span>
Global and macro attribute list attributes are substituted in the
  macro&#8217;s markup template.
</span>
</li>
<li>
<span>
The substituted template replaces the macro reference in the output
  document.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X98">22. HTML 5 audio and video block macros</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="22. HTML 5 audio and video block macros";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <em>html5</em> backend <em>audio</em> and <em>video</em> block macros generate the HTML
5 <em>audio</em> and <em>video</em> elements respectively.  They follow the usual
AsciiDoc block macro syntax <tt>&lt;name&gt;::&lt;target&gt;[&lt;attrlist&gt;]</tt> where:</p>
</div>
<div class="hdlist"><table>
<tr>
<td class="hdlist1">
<tt>&lt;name&gt;</tt>
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
<em>audio</em> or <em>video</em>.
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<tt>&lt;target&gt;</tt>
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
The URL or file name of the video or audio file.
</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<tt>&lt;attrlist&gt;</tt>
<br />
</td>
<td class="hdlist2">
<p style="margin-top: 0;">
A list of named attributes (see below).
</p>
</td>
</tr>
</table></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="hsides"
cellspacing="0" cellpadding="4">
<caption class="title">Table 4. Audio macro attributes</caption>
<col width="16%" />
<col width="83%" />
<thead>
<tr>
<th align="left" valign="top">Name </th>
<th align="left" valign="top"> Value</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">options</p></td>
<td align="left" valign="top"><p class="table">A comma separated list of one or more of the following items:
<em>autoplay</em>, <em>loop</em> which correspond to the same-named HTML 5 <em>audio</em>
element boolean attributes.  By default the player <em>controls</em> are
enabled, include the <em>nocontrols</em> option value to hide them.</p></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
width="100%"
frame="hsides"
cellspacing="0" cellpadding="4">
<caption class="title">Table 5. Video macro attributes</caption>
<col width="16%" />
<col width="83%" />
<thead>
<tr>
<th align="left" valign="top">Name   </th>
<th align="left" valign="top"> Value</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">height</p></td>
<td align="left" valign="top"><p class="table">The height of the player in pixels.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">width</p></td>
<td align="left" valign="top"><p class="table">The width of the player in pixels.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">poster</p></td>
<td align="left" valign="top"><p class="table">The URL or file name of an image representing the video.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">options</p></td>
<td align="left" valign="top"><p class="table">A comma separated list of one or more of the following items:
<em>autoplay</em>, <em>loop</em> and <em>nocontrols</em>. The <em>autoplay</em> and <em>loop</em> options
correspond to the same-named HTML 5 <em>video</em> element boolean
attributes.  By default the player <em>controls</em> are enabled, include the
<em>nocontrols</em> option value to hide them.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph">
<p>Examples:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>audio::images/example.ogg[]

video::gizmo.ogv[width=200,options="nocontrols,autoplay"]

.Example video
video::gizmo.ogv[]

video::http://www.808.dk/pics/video/gizmo.ogv[]</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>If your needs are more complex put raw HTML 5 in a markup block, for
example (from <a href="http://www.808.dk/?code-html-5-video">http://www.808.dk/?code-html-5-video</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>++++
&lt;video poster="pics/video/gizmo.jpg" id="video" style="cursor: pointer;" &gt;
  &lt;source src="pics/video/gizmo.mp4" /&gt;
  &lt;source src="pics/video/gizmo.webm" type="video/webm" /&gt;
  &lt;source src="pics/video/gizmo.ogv" type="video/ogg" /&gt;
  Video not playing? &lt;a href="pics/video/gizmo.mp4"&gt;Download file&lt;/a&gt; instead.
&lt;/video&gt;

&lt;script type="text/javascript"&gt;
  var video = document.getElementById('video');
  video.addEventListener('click',function(){
    video.play();
  },false);
&lt;/script&gt;
++++</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_tables">23. Tables</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="23. Tables";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The AsciiDoc table syntax looks and behaves like other delimited block
types and supports standard <a href="#X73">block configuration entries</a>.
Formatting is easy to read and, just as importantly, easy to enter.</p>
</div>
<ul class="">
<li>
<span>
Cells and columns can be formatted using built-in customizable styles.
</span>
</li>
<li>
<span>
Horizontal and vertical cell alignment can be set on columns and
  cell.
</span>
</li>
<li>
<span>
Horizontal and vertical cell spanning is supported.
</span>
</li>
</ul>
<div class="sidebarblock">
<div class="content">
<div class="title">Use tables sparingly</div>
<div class="paragraph">
<p>When technical users first start creating documents, tables (complete
with column spanning and table nesting) are often considered very
important. The reality is that tables are seldom used, even in
technical documentation.</p>
</div>
<div class="paragraph">
<p>Try this exercise: thumb through your library of technical books,
you&#8217;ll be surprised just how seldom tables are actually used, even
less seldom are tables containing block elements (such as paragraphs
or lists) or spanned cells. This is no accident, like figures, tables
are outside the normal document flow&#8201;&#8212;&#8201;tables are for consulting not
for reading.</p>
</div>
<div class="paragraph">
<p>Tables are designed for, and should normally only be used for,
displaying column oriented tabular data.</p>
</div>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_example_tables">23.1. Example tables</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="23.1. Example tables";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="tableblock">
<table rules="all"
width="15%"
frame="border"
cellspacing="0" cellpadding="4">
<caption class="title">Table 6. Simple table</caption>
<col width="33%" />
<col width="33%" />
<col width="33%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">1</p></td>
<td align="left" valign="top"><p class="table">2</p></td>
<td align="left" valign="top"><p class="table">A</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">3</p></td>
<td align="left" valign="top"><p class="table">4</p></td>
<td align="left" valign="top"><p class="table">B</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">5</p></td>
<td align="left" valign="top"><p class="table">6</p></td>
<td align="left" valign="top"><p class="table">C</p></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="listingblock">
<div class="title">AsciiDoc source</div>
<div class="content">
<pre><tt>[width="15%"]
|=======
|1 |2 |A
|3 |4 |B
|5 |6 |C
|=======</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
width="50%"
frame="hsides"
cellspacing="0" cellpadding="4">
<caption class="title">Table 7. Columns formatted with strong, monospaced and emphasis styles</caption>
<col width="33%" />
<col width="33%" />
<col width="33%" />
<thead>
<tr>
<th align="right" valign="top">      </th>
<th colspan="2" align="center" valign="top">Columns 2 and 3</th>
</tr>
</thead>
<tfoot>
<tr>
<td align="right" valign="top"><p class="table"><strong>footer 1</strong></p></td>
<td align="center" valign="top"><p class="table"><tt>footer 2</tt></p></td>
<td align="left" valign="top"><p class="table"><em>footer 3</em></p></td>
</tr>
</tfoot>
<tbody>
<tr>
<td align="right" valign="top"><p class="table"><strong>1</strong></p></td>
<td align="center" valign="top"><p class="table"><tt>Item 1</tt></p></td>
<td align="left" valign="top"><p class="table"><em>Item 1</em></p></td>
</tr>
<tr>
<td align="right" valign="top"><p class="table"><strong>2</strong></p></td>
<td align="center" valign="top"><p class="table"><tt>Item 2</tt></p></td>
<td align="left" valign="top"><p class="table"><em>Item 2</em></p></td>
</tr>
<tr>
<td align="right" valign="top"><p class="table"><strong>3</strong></p></td>
<td align="center" valign="top"><p class="table"><tt>Item 3</tt></p></td>
<td align="left" valign="top"><p class="table"><em>Item 3</em></p></td>
</tr>
<tr>
<td align="right" valign="top"><p class="table"><strong>4</strong></p></td>
<td align="center" valign="top"><p class="table"><tt>Item 4</tt></p></td>
<td align="left" valign="top"><p class="table"><em>Item 4</em></p></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="listingblock">
<div class="title">AsciiDoc source</div>
<div class="content">
<pre><tt>.An example table
[width="50%",cols="&gt;s,^m,e",frame="topbot",options="header,footer"]
|==========================
|      2+|Columns 2 and 3
|1       |Item 1  |Item 1
|2       |Item 2  |Item 2
|3       |Item 3  |Item 3
|4       |Item 4  |Item 4
|footer 1|footer 2|footer 3
|==========================</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
width="80%"
frame="border"
cellspacing="0" cellpadding="4">
<caption class="title">Table 8. Horizontal and vertical source data</caption>
<col width="17%" />
<col width="11%" />
<col width="11%" />
<col width="58%" />
<thead>
<tr>
<th align="left" valign="top">Date </th>
<th align="center" valign="top">Duration </th>
<th align="center" valign="top">Avg HR </th>
<th align="left" valign="top">Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">22-Aug-08</p></td>
<td align="center" valign="top"><p class="table">10:24</p></td>
<td align="center" valign="top"><p class="table">157</p></td>
<td align="left" valign="top"><p class="table">Worked out MSHR (max sustainable heart rate) by going hard
for this interval.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">22-Aug-08</p></td>
<td align="center" valign="top"><p class="table">23:03</p></td>
<td align="center" valign="top"><p class="table">152</p></td>
<td align="left" valign="top"><p class="table">Back-to-back with previous interval.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">24-Aug-08</p></td>
<td align="center" valign="top"><p class="table">40:00</p></td>
<td align="center" valign="top"><p class="table">145</p></td>
<td align="left" valign="top"><p class="table">Moderately hard interspersed with 3x 3min intervals (2min
hard + 1min really hard taking the HR up to 160).</p></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Short cells can be entered horizontally, longer cells vertically.  The
default behavior is to strip leading and trailing blank lines within a
cell. These characteristics aid readability and data entry.</p>
</div>
<div class="listingblock">
<div class="title">AsciiDoc source</div>
<div class="content">
<pre><tt>.Windtrainer workouts
[width="80%",cols="3,^2,^2,10",options="header"]
|=========================================================
|Date |Duration |Avg HR |Notes

|22-Aug-08 |10:24 | 157 |
Worked out MSHR (max sustainable heart rate) by going hard
for this interval.

|22-Aug-08 |23:03 | 152 |
Back-to-back with previous interval.

|24-Aug-08 |40:00 | 145 |
Moderately hard interspersed with 3x 3min intervals (2min
hard + 1min really hard taking the HR up to 160).

|=========================================================</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<caption class="title">Table 9. A table with externally sourced CSV data</caption>
<col width="11%" />
<col width="22%" />
<col width="22%" />
<col width="22%" />
<col width="22%" />
<thead>
<tr>
<th align="center" valign="top">ID</th>
<th align="left" valign="top">Customer Name</th>
<th align="left" valign="top">Contact Name</th>
<th align="left" valign="top">Customer Address</th>
<th align="left" valign="top">Phone</th>
</tr>
</thead>
<tbody>
<tr>
<td align="center" valign="top"><p class="table">AROUT</p></td>
<td align="left" valign="top"><p class="table">Around the Horn</p></td>
<td align="left" valign="top"><p class="table">Thomas Hardy</p></td>
<td align="left" valign="top"><p class="table">120 Hanover Sq.
London</p></td>
<td align="left" valign="top"><p class="table">(171) 555-7788</p></td>
</tr>
<tr>
<td align="center" valign="top"><p class="table">BERGS</p></td>
<td align="left" valign="top"><p class="table">Berglunds snabbkop</p></td>
<td align="left" valign="top"><p class="table">Christina Berglund</p></td>
<td align="left" valign="top"><p class="table">Berguvsvagen  8
Lulea</p></td>
<td align="left" valign="top"><p class="table">0921-12 34 65</p></td>
</tr>
<tr>
<td align="center" valign="top"><p class="table">BLAUS</p></td>
<td align="left" valign="top"><p class="table">Blauer See Delikatessen</p></td>
<td align="left" valign="top"><p class="table">Hanna Moos</p></td>
<td align="left" valign="top"><p class="table">Forsterstr. 57
Mannheim</p></td>
<td align="left" valign="top"><p class="table">0621-08460</p></td>
</tr>
<tr>
<td align="center" valign="top"><p class="table">BLONP</p></td>
<td align="left" valign="top"><p class="table">Blondel pere et fils</p></td>
<td align="left" valign="top"><p class="table">Frederique Citeaux</p></td>
<td align="left" valign="top"><p class="table">24, place Kleber
Strasbourg</p></td>
<td align="left" valign="top"><p class="table">88.60.15.31</p></td>
</tr>
<tr>
<td align="center" valign="top"><p class="table">BOLID</p></td>
<td align="left" valign="top"><p class="table">Bolido Comidas preparadas</p></td>
<td align="left" valign="top"><p class="table">Martin Sommer</p></td>
<td align="left" valign="top"><p class="table">C/ Araquil, 67
Madrid</p></td>
<td align="left" valign="top"><p class="table">(91) 555 22 82</p></td>
</tr>
<tr>
<td align="center" valign="top"><p class="table">BONAP</p></td>
<td align="left" valign="top"><p class="table">Bon app'</p></td>
<td align="left" valign="top"><p class="table">Laurence Lebihan</p></td>
<td align="left" valign="top"><p class="table">12, rue des Bouchers
Marseille</p></td>
<td align="left" valign="top"><p class="table">91.24.45.40</p></td>
</tr>
<tr>
<td align="center" valign="top"><p class="table">BOTTM</p></td>
<td align="left" valign="top"><p class="table">Bottom-Dollar Markets</p></td>
<td align="left" valign="top"><p class="table">Elizabeth Lincoln</p></td>
<td align="left" valign="top"><p class="table">23 Tsawassen Blvd.
Tsawassen</p></td>
<td align="left" valign="top"><p class="table">(604) 555-4729</p></td>
</tr>
<tr>
<td align="center" valign="top"><p class="table">BSBEV</p></td>
<td align="left" valign="top"><p class="table">B&#8217;s Beverages</p></td>
<td align="left" valign="top"><p class="table">Victoria Ashworth</p></td>
<td align="left" valign="top"><p class="table">Fauntleroy Circus
London</p></td>
<td align="left" valign="top"><p class="table">(171) 555-1212</p></td>
</tr>
<tr>
<td align="center" valign="top"><p class="table">CACTU</p></td>
<td align="left" valign="top"><p class="table">Cactus Comidas para llevar</p></td>
<td align="left" valign="top"><p class="table">Patricio Simpson</p></td>
<td align="left" valign="top"><p class="table">Cerrito 333
Buenos Aires</p></td>
<td align="left" valign="top"><p class="table">(1) 135-5555</p></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="listingblock">
<div class="title">AsciiDoc source</div>
<div class="content">
<pre><tt>[format="csv",cols="^1,4*2",options="header"]
|===================================================
ID,Customer Name,Contact Name,Customer Address,Phone
include::customers.csv[]
|===================================================</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
width="25%"
frame="border"
cellspacing="0" cellpadding="4">
<caption class="title">Table 10. Cell spans, alignments and styles</caption>
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><em>1</em></p></td>
<td align="right" valign="top"><p class="table"><strong>2</strong></p></td>
<td align="center" valign="top"><p class="table">3</p></td>
<td align="right" valign="top"><p class="table"><strong>4</strong></p></td>
</tr>
<tr>
<td align="center" valign="top"><p class="table"><em>5</em></p></td>
<td colspan="2" rowspan="2" align="center" valign="middle"><p class="table"><tt>6</tt></p></td>
<td rowspan="3" align="left" valign="bottom"><p class="table"><tt>7</tt></p></td>
</tr>
<tr>
<td align="center" valign="top"><p class="table"><em>8</em></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>9</em></p></td>
<td colspan="2" align="right" valign="top"><p class="table"><tt>10</tt></p></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="listingblock">
<div class="title">AsciiDoc source</div>
<div class="content">
<pre><tt>[cols="e,m,^,&gt;s",width="25%"]
|============================
|1 &gt;s|2 |3 |4
^|5 2.2+^.^|6 .3+&lt;.&gt;m|7
^|8
|9 2+&gt;|10
|============================</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X68">23.2. Table input data formats</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="23.2. Table input data formats";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc table data can be <em>psv</em>, <em>dsv</em> or <em>csv</em> formatted.  The
default table format is <em>psv</em>.</p>
</div>
<div class="paragraph">
<p>AsciiDoc <em>psv</em> (<em>Prefix Separated Values</em>) and <em>dsv</em> (<em>Delimiter
Separated Values</em>) formats are cell oriented&#8201;&#8212;&#8201;the table is treated
as a sequence of cells&#8201;&#8212;&#8201;there are no explicit row separators.</p>
</div>
<ul class="">
<li>
<span>
<em>psv</em> prefixes each cell with a separator whereas <em>dsv</em> delimits
  cells with a separator.
</span>
</li>
<li>
<span>
<em>psv</em> and <em>dsv</em> separators are Python regular expressions.
</span>
</li>
<li>
<span>
The default <em>psv</em> separator contains <a href="#X84">cell specifier</a> related
  named regular expression groups.
</span>
</li>
<li>
<span>
The default <em>dsv</em> separator is <tt>:|\n</tt> (a colon or a new line
  character).
</span>
</li>
<li>
<span>
<em>psv</em> and <em>dsv</em> cell separators can be escaped by preceding them
  with a backslash character.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Here are four <em>psv</em> cells (the second item spans two columns; the
last contains an escaped separator):</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>|One 2+|Two and three |A \| separator character</tt></pre>
</div></div>
<div class="paragraph">
<p><em>csv</em>  is the quasi-standard row oriented <em>Comma Separated Values
(CSV)</em> format commonly used to import and export spreadsheet and
database data.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X69">23.3. Table attributes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="23.3. Table attributes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Tables can be customized by the following attributes:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
format
</dt>
<dd>
<p>
<em>psv</em> (default), <em>dsv</em> or <em>csv</em> (See <a href="#X68">Table Data Formats</a>).
</p>
</dd>
<dt class="hdlist1">
separator
</dt>
<dd>
<p>
The cell separator. A Python regular expression (<em>psv</em> and <em>dsv</em>
formats) or a single character (<em>csv</em> format).
</p>
</dd>
<dt class="hdlist1">
frame
</dt>
<dd>
<p>
Defines the table border and can take the following values: <em>topbot</em>
(top and bottom), <em>all</em> (all sides), <em>none</em> and <em>sides</em> (left and
right sides). The default value is <em>all</em>.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
grid
</dt>
<dd>
<p>
Defines which ruler lines are drawn between table rows and columns.
The <em>grid</em> attribute value can be any of the following values: <em>none</em>,
<em>cols</em>, <em>rows</em> and <em>all</em>. The default value is <em>all</em>.
</p>
</dd>
<dt class="hdlist1">
align
</dt>
<dd>
<p>
Use the <em>align</em> attribute to horizontally align the table on the
page (works with HTML outputs only, has no effect on DocBook outputs).
The following values are valid: <em>left</em>, <em>right</em>, and <em>center</em>.
</p>
</dd>
<dt class="hdlist1">
float
</dt>
<dd>
<p>
Use the <em>float</em> attribute to float the table <em>left</em> or <em>right</em> on the
page (works with HTML outputs only, has no effect on DocBook outputs).
Floating only makes sense in conjunction with a table <em>width</em>
attribute value of less than 100% (otherwise the table will take up
all the available space).  <em>float</em> and <em>align</em> attributes are mutually
exclusive.  Use the <tt>unfloat::[]</tt> block macro to stop floating.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
halign
</dt>
<dd>
<p>
Use the <em>halign</em> attribute to horizontally align all cells in a table.
The following values are valid: <em>left</em>, <em>right</em>, and <em>center</em>
(defaults to <em>left</em>). Overridden by <a href="#X70">Column specifiers</a>  and
<a href="#X84">Cell specifiers</a>.
</p>
</dd>
<dt class="hdlist1">
valign
</dt>
<dd>
<p>
Use the <em>valign</em> attribute to vertically align all cells in a table.
The following values are valid: <em>top</em>, <em>bottom</em>, and <em>middle</em>
(defaults to <em>top</em>). Overridden by <a href="#X70">Column specifiers</a>  and
<a href="#X84">Cell specifiers</a>.
</p>
</dd>
<dt class="hdlist1">
options
</dt>
<dd>
<p>
The <em>options</em> attribute can contain comma separated values, for
example: <em>header</em>, <em>footer</em>. By default header and footer rows are
omitted.  See <a href="#X74">attribute options</a> for a complete list of
available table options.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
cols
</dt>
<dd>
<p>
The <em>cols</em> attribute is a comma separated list of <a href="#X70">column specifiers</a>. For example <tt>cols="2&lt;p,2*,4p,&gt;"</tt>.
</p>
<ul class="">
<li>
<span>
If <em>cols</em> is present it must specify all columns.
</span>
</li>
<li>
<span>
If the <em>cols</em> attribute is not specified the number of columns is
  calculated as the number of data items in the <strong>first line</strong> of the
  table.
</span>
</li>
<li>
<span>
The degenerate form for the <em>cols</em> attribute is an integer
  specifying the number of columns e.g. <tt>cols=4</tt>.
</span>
</li>
</ul>
</dd>
<dt class="hdlist1">
width
</dt>
<dd>
<p>
The <em>width</em> attribute is expressed as a percentage value
(<em>"1%"</em>&#8230;<em>"99%"</em>). The width specifies the table width relative to
the available width. HTML backends use this value to set the table
width attribute. It&#8217;s a bit more complicated with DocBook, see the
<a href="#X89">DocBook table widths</a> sidebar.
</p>
</dd>
<dt class="hdlist1">
filter
</dt>
<dd>
<p>
The <em>filter</em> attribute defines an external shell command that is
invoked for each cell. The built-in <em>asciidoc</em> table style is
implemented using a filter.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="sidebarblock" id="X89">
<div class="content">
<div class="title">DocBook table widths</div>
<div class="paragraph">
<p>The AsciiDoc docbook backend generates CALS tables. CALS tables do not
support a table width attribute&#8201;&#8212;&#8201;table width can only be controlled
by specifying absolute column widths.</p>
</div>
<div class="paragraph">
<p>Specifying absolute column widths is not media independent because
different presentation media have different physical dimensions. To
get round this limitation both
<a href="http://www.sagehill.net/docbookxsl/Tables.html#TableWidth">DocBook XSL
Stylesheets</a> and
<a href="http://dblatex.sourceforge.net/doc/manual/ch03s05.html#sec-table-width">dblatex</a>
have implemented table width processing instructions for setting the
table width as a percentage of the available width. AsciiDoc emits
these processing instructions if the <em>width</em> attribute is set along
with proportional column widths (the AsciiDoc docbook backend
<em>pageunits</em> attribute defaults to <em>*</em>).</p>
</div>
<div class="paragraph">
<p>To generate DocBook tables with absolute column widths set the
<em>pageunits</em> attribute to a CALS absolute unit such as <em>pt</em> and set the
<em>pagewidth</em> attribute to match the width of the presentation media.</p>
</div>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X70">23.4. Column Specifiers</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="23.4. Column Specifiers";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Column specifiers define how columns are rendered and appear in the
table <a href="#X69">cols attribute</a>.  A column specifier consists of an
optional column multiplier followed by optional alignment, width and
style values and is formatted like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[&lt;multiplier&gt;*][&lt;align&gt;][&lt;width&gt;][&lt;style&gt;]</tt></pre>
</div></div>
<ul class="">
<li>
<span>
All components are optional. The multiplier must be first and the
  style last. The order of <tt>&lt;align&gt;</tt> or <tt>&lt;width&gt;</tt> is not important.
</span>
</li>
<li>
<span>
Column <tt>&lt;width&gt;</tt> can be either an integer proportional value (1&#8230;)
  or a percentage (1%&#8230;100%). The default value is 1. To ensure
  portability across different backends, there is no provision for
  absolute column widths (not to be confused with output column width
  <a href="#X72">markup attributes</a> which are available in both percentage and
  absolute units).
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<ul class="">
<li>
<span>
The <em>&lt;align&gt;</em> column alignment specifier is formatted like:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>[&lt;horizontal&gt;][.&lt;vertical&gt;]</tt></pre>
</div></div>
<div class="paragraph">
<p>Where <tt>&lt;horizontal&gt;</tt> and <tt>&lt;vertical&gt;</tt> are one of the following
characters: <tt>&lt;</tt>, <tt>^</tt> or <tt>&gt;</tt> which represent <em>left</em>, <em>center</em> and
<em>right</em> horizontal alignment or <em>top</em>, <em>middle</em> and <em>bottom</em> vertical
alignment respectively.</p>
</div>
</li>
<li>
<span>
A <tt>&lt;multiplier&gt;</tt> can be used to specify repeated columns e.g.
  <tt>cols="4*&lt;"</tt> specifies four left-justified columns. The default
  multiplier value is 1.
</span>
</li>
<li>
<span>
The <tt>&lt;style&gt;</tt> name specifies a <a href="#X71">table style</a> to used to markup
  column cells (you can use the full style names if you wish but the
  first letter is normally sufficient).
</span>
</li>
<li>
<span>
Column specific styles are not applied to header rows.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X84">23.5. Cell Specifiers</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="23.5. Cell Specifiers";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Cell specifiers allow individual cells in <em>psv</em> formatted tables to be
spanned, multiplied, aligned and styled.  Cell specifiers prefix <em>psv</em>
<tt>|</tt> delimiters and are formatted like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[&lt;span&gt;*|+][&lt;align&gt;][&lt;style&gt;]</tt></pre>
</div></div>
<ul class="">
<li>
<span>
<em>&lt;span&gt;</em> specifies horizontal and vertical cell spans (<em>+</em> operator) or
  the number of times the cell is replicated (<em>*</em> operator). <em>&lt;span&gt;</em>
  is formatted like:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>[&lt;colspan&gt;][.&lt;rowspan&gt;]</tt></pre>
</div></div>
<div class="paragraph">
<p>Where <tt>&lt;colspan&gt;</tt> and <tt>&lt;rowspan&gt;</tt> are integers specifying the number of
columns and rows to span.</p>
</div>
</li>
<li>
<span>
<tt>&lt;align&gt;</tt> specifies horizontal and vertical cell alignment an is the
  same as in <a href="#X70">column specifiers</a>.
</span>
</li>
<li>
<span>
A <tt>&lt;style&gt;</tt> value is the first letter of <a href="#X71">table style</a> name.
</span>
</li>
</ul>
<div class="paragraph">
<p>For example, the following <em>psv</em> formatted cell will span two columns
and the text will be centered and emphasized:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>`2+^e| Cell text`</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X71">23.6. Table styles</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="23.6. Table styles";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Table styles can be applied to the entire table (by setting the
<em>style</em> attribute in the table&#8217;s attribute list) or on a per column
basis (by specifying the style in the table&#8217;s <a href="#X69">cols attribute</a>).
Table data can be formatted using the following predefined styles:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
default
</dt>
<dd>
<p>
The default style: AsciiDoc inline text formatting; blank lines are
treated as paragraph breaks.
</p>
</dd>
<dt class="hdlist1">
emphasis
</dt>
<dd>
<p>
Like default but all text is emphasised.
</p>
</dd>
<dt class="hdlist1">
monospaced
</dt>
<dd>
<p>
Like default but all text is in a monospaced font.
</p>
</dd>
<dt class="hdlist1">
strong
</dt>
<dd>
<p>
Like default but all text is bold.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
header
</dt>
<dd>
<p>
Apply the same style as the table header. Normally used to create a
vertical header in the first column.
</p>
</dd>
<dt class="hdlist1">
asciidoc
</dt>
<dd>
<p>
With this style table cells can contain any of the AsciiDoc elements
that are allowed inside document sections. This style runs <tt>asciidoc(1)</tt>
as a filter to process cell contents. See also <a href="#X83">Docbook table limitations</a>.
</p>
</dd>
<dt class="hdlist1">
literal
</dt>
<dd>
<p>
No text formatting; monospaced font; all line breaks are retained
(the same as the AsciiDoc <a href="#X65">LiteralBlock</a> element).
</p>
</dd>
<dt class="hdlist1">
verse
</dt>
<dd>
<p>
All line breaks are retained (just like the AsciiDoc <a href="#X94">verse paragraph style</a>).
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X72">23.7. Markup attributes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="23.7. Markup attributes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc makes a number of attributes available to table markup
templates and tags. Column specific attributes are available when
substituting the <em>colspec</em> cell data tags.</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
pageunits
</dt>
<dd>
<p>
DocBook backend only. Specifies table column absolute width units.
Defaults to <em>*</em>.
</p>
</dd>
<dt class="hdlist1">
pagewidth
</dt>
<dd>
<p>
DocBook backend only. The nominal output page width in <em>pageunit</em>
units. Used to calculate CALS tables absolute column and table
widths. Defaults to <em>425</em>.
</p>
</dd>
<dt class="hdlist1">
tableabswidth
</dt>
<dd>
<p>
Integer value calculated from <em>width</em> and <em>pagewidth</em> attributes.
In <em>pageunit</em> units.
</p>
</dd>
<dt class="hdlist1">
tablepcwidth
</dt>
<dd>
<p>
Table width expressed as a percentage of the available width. Integer
value (0..100).
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
colabswidth
</dt>
<dd>
<p>
Integer value calculated from <em>cols</em> column width, <em>width</em> and
<em>pagewidth</em> attributes.  In <em>pageunit</em> units.
</p>
</dd>
<dt class="hdlist1">
colpcwidth
</dt>
<dd>
<p>
Column width expressed as a percentage of the table width. Integer
value (0..100).
</p>
</dd>
<dt class="hdlist1">
colcount
</dt>
<dd>
<p>
Total number of table columns.
</p>
</dd>
<dt class="hdlist1">
rowcount
</dt>
<dd>
<p>
Total number of table rows.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
halign
</dt>
<dd>
<p>
Horizontal cell content alignment: <em>left</em>, <em>right</em> or <em>center</em>.
</p>
</dd>
<dt class="hdlist1">
valign
</dt>
<dd>
<p>
Vertical cell content alignment: <em>top</em>, <em>bottom</em> or <em>middle</em>.
</p>
</dd>
<dt class="hdlist1">
colnumber, colstart
</dt>
<dd>
<p>
The number of the leftmost column occupied by the cell (1&#8230;).
</p>
</dd>
<dt class="hdlist1">
colend
</dt>
<dd>
<p>
The number of the rightmost column occupied by the cell (1&#8230;).
</p>
</dd>
<dt class="hdlist1">
colspan
</dt>
<dd>
<p>
Number of columns the cell should span.
</p>
</dd>
<dt class="hdlist1">
rowspan
</dt>
<dd>
<p>
Number of rows the cell should span (1&#8230;).
</p>
</dd>
<dt class="hdlist1">
morerows
</dt>
<dd>
<p>
Number of additional rows the cell should span (0&#8230;).
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_nested_tables">23.8. Nested tables</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="23.8. Nested tables";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>An alternative <em>psv</em> separator character <em>!</em> can be used (instead of
<em>|</em>) in nested tables. This allows a single level of table nesting.
Columns containing nested tables must use the <em>asciidoc</em> style. An
example can be found in <tt>./examples/website/newtables.txt</tt>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X83">23.9. DocBook table limitations</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="23.9. DocBook table limitations";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Fully implementing tables is not trivial, some DocBook toolchains do
better than others.  AsciiDoc HTML table outputs are rendered
correctly in all the popular browsers&#8201;&#8212;&#8201;if your DocBook generated
tables don&#8217;t look right compare them with the output generated by the
AsciiDoc <em>xhtml11</em> backend or try a different DocBook toolchain.  Here
is a list of things to be aware of:</p>
</div>
<ul class="">
<li>
<span>
Although nested tables are not legal in DocBook 4 the FOP and
  dblatex toolchains will process them correctly.  If you use <tt>a2x(1)</tt>
  you will need to include the <tt>--no-xmllint</tt> option to suppress
  DocBook validation errors.
</span>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">In theory you can nest DocBook 4 tables one level using the
<em>entrytbl</em> element, but not all toolchains process <em>entrytbl</em>.</td>
</tr></table>
</div>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<ul class="">
<li>
<span>
DocBook only allows a subset of block elements inside table cells so
  not all AsciiDoc elements produce valid DocBook inside table cells.
  If you get validation errors running <tt>a2x(1)</tt> try the <tt>--no-xmllint</tt>
  option, toolchains will often process nested block elements such as
  sidebar blocks and floating titles correctly even though, strictly
  speaking, they are not legal.
</span>
</li>
<li>
<span>
Text formatting in cells using the <em>monospaced</em> table style will
  raise validation errors because the DocBook <em>literal</em> element was
  not designed to support formatted text (using the <em>literal</em> element
  is a kludge on the part of AsciiDoc as there is no easy way to set
  the font style in DocBook.
</span>
</li>
<li>
<span>
Cell alignments are ignored for <em>verse</em>, <em>literal</em> or <em>asciidoc</em>
  table styles.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X1">24. Manpage Documents</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="24. Manpage Documents";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Sooner or later, if you program in a UNIX environment, you&#8217;re going
to have to write a man page.</p>
</div>
<div class="paragraph">
<p>By observing a couple of additional conventions you can compose
AsciiDoc files that will generate DocBook refentry (man page)
documents.  The resulting DocBook file can then be translated to the
native roff man page format (or other formats).</p>
</div>
<div class="paragraph">
<p>For example, the <tt>asciidoc.1.txt</tt> file in the AsciiDoc distribution
<tt>./doc</tt> directory was used to generate both the
<tt>asciidoc.1.css-embedded.html</tt> HTML file the <tt>asciidoc.1</tt> roff
formatted <tt>asciidoc(1)</tt> man page.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="sidebarblock">
<div class="content">
<div class="title">Viewing and printing manpage files</div>
<div class="paragraph">
<p>Use the <tt>man(1)</tt> command to view the manpage file:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ man -l asciidoc.1</tt></pre>
</div></div>
<div class="paragraph">
<p>To print a high quality man page to a postscript printer:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ man -l -Tps asciidoc.1 | lpr</tt></pre>
</div></div>
<div class="paragraph">
<p>You could also create a PDF version of the man page by converting
PostScript to PDF using <tt>ps2pdf(1)</tt>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ man -l -Tps asciidoc.1 | ps2pdf - asciidoc.1.pdf</tt></pre>
</div></div>
<div class="paragraph">
<p>The <tt>ps2pdf(1)</tt> command is included in the Ghostscript distribution.</p>
</div>
</div></div>
<div class="paragraph">
<p>To find out more about man pages view the <tt>man(7)</tt> manpage
(<tt>man 7 man</tt> and <tt>man man-pages</tt> commands).</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_document_header">24.1. Document Header</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="24.1. Document Header";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>A manpage document Header is mandatory. The title line contains the
man page name followed immediately by the manual section number in
brackets, for example <em>ASCIIDOC(1)</em>. The title name should not contain
white space and the manual section number is a single digit optionally
followed by a single character.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="_the_name_section">24.2. The NAME Section</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="24.2. The NAME Section";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The first manpage section is mandatory, must be titled <em>NAME</em> and must
contain a single paragraph (usually a single line) consisting of a
list of one or more comma separated command name(s) separated from the
command purpose by a dash character. The dash must have at least one
white space character on either side. For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>printf, fprintf, sprintf - print formatted output</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_the_synopsis_section">24.3. The SYNOPSIS Section</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="24.3. The SYNOPSIS Section";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The second manpage section is mandatory and must be titled <em>SYNOPSIS</em>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_refmiscinfo_attributes">24.4. refmiscinfo attributes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="24.4. refmiscinfo attributes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>In addition to the automatically created man page <a href="#X60">intrinsic attributes</a> you can assign DocBook
<a href="http://www.docbook.org/tdg5/en/html/refmiscinfo.html">refmiscinfo</a>
element <em>source</em>, <em>version</em> and <em>manual</em> values using AsciiDoc
<tt>{mansource}</tt>, <tt>{manversion}</tt> and <tt>{manmanual}</tt> attributes
respectively. This example is from the AsciiDoc header of a man page
source file:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>:man source:   AsciiDoc
:man version:  {revnumber}
:man manual:   AsciiDoc Manual</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X78">25. Mathematical Formulas</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="25. Mathematical Formulas";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <em>asciimath</em> and <em>latexmath</em> <a href="#X77">passthrough macros</a> along with
<em>asciimath</em> and <em>latexmath</em>  <a href="#X76">passthrough blocks</a> provide a
(backend dependent) mechanism for rendering mathematical formulas. You
can use the following math markups:</p>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">The <em>latexmath</em> macro used to include <em>LaTeX Math</em> in DocBook
outputs is not the same as the <em>latexmath</em> macro used to include
<em>LaTeX MathML</em> in XHTML outputs.  <em>LaTeX Math</em> applies to DocBook
outputs that are processed by <a href="#X31">dblatex</a> and is normally used to
generate PDF files.  <em>LaTeXMathML</em> is very much a subset of <em>LaTeX
Math</em> and applies to XHTML documents.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_latex_math">25.1. LaTeX Math</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="25.1. LaTeX Math";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p><a href="ftp://ftp.ams.org/pub/tex/doc/amsmath/short-math-guide.pdf">LaTeX
math</a> can be included in documents that are processed by
<a href="#X31">dblatex(1)</a>.  Example inline formula:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$]</tt></pre>
</div></div>
<div class="paragraph">
<p>For more examples see the <a href="http://www.methods.co.nz/asciidoc/">AsciiDoc website</a> or the
distributed <tt>doc/latexmath.txt</tt> file.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_asciimathml">25.2. ASCIIMathML</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="25.2. ASCIIMathML";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p><a href="http://www1.chapman.edu/~jipsen/mathml/asciimath.html">ASCIIMathML</a>
formulas can be included in XHTML documents generated using the
<em>xhtml11</em> and <em>html5</em> backends. To enable ASCIIMathML support you must
define the <em>asciimath</em> attribute, for example using the <tt>-a asciimath</tt>
command-line option.  Example inline formula:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>asciimath:[`x/x={(1,if x!=0),(text{undefined},if x=0):}`]</tt></pre>
</div></div>
<div class="paragraph">
<p>For more examples see the <a href="http://www.methods.co.nz/asciidoc/">AsciiDoc website</a> or the
distributed <tt>doc/asciimathml.txt</tt> file.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_latexmathml">25.3. LaTeXMathML</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="25.3. LaTeXMathML";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p><em>LaTeXMathML</em> allows LaTeX Math style formulas to be included in XHTML
documents generated using the AsciiDoc <em>xhtml11</em> and <em>html5</em> backends.
AsciiDoc uses the
<a href="http://www.maths.nottingham.ac.uk/personal/drw/lm.html">original
LaTeXMathML</a> by Douglas Woodall.  <em>LaTeXMathML</em> is derived from
ASCIIMathML and is for users who are more familiar with or prefer
using LaTeX math formulas (it recognizes a subset of LaTeX Math, the
differences are documented on the <em>LaTeXMathML</em> web page).  To enable
LaTeXMathML support you must define the <em>latexmath</em> attribute, for
example using the <tt>-a latexmath</tt> command-line option.  Example inline
formula:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>latexmath:[$\sum_{n=1}^\infty \frac{1}{2^n}$]</tt></pre>
</div></div>
<div class="paragraph">
<p>For more examples see the <a href="http://www.methods.co.nz/asciidoc/">AsciiDoc website</a> or the
distributed <tt>doc/latexmathml.txt</tt> file.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="_mathml">25.4. MathML</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="25.4. MathML";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p><a href="http://www.w3.org/Math/">MathML</a> is a low level XML markup for
mathematics. AsciiDoc has no macros for MathML but users familiar with
this markup could use passthrough macros and passthrough blocks to
include MathML in output documents.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X7">26. Configuration Files</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="26. Configuration Files";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc source file syntax and output file markup is largely
controlled by a set of cascading, text based, configuration files.  At
runtime The AsciiDoc default configuration files are combined with
optional user and document specific configuration files.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_configuration_file_format">26.1. Configuration File Format</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="26.1. Configuration File Format";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Configuration files contain named sections. Each section begins with a
section name in square brackets []. The section body consists of the
lines of text between adjacent section headings.</p>
</div>
<ul class="">
<li>
<span>
Section names consist of one or more alphanumeric, underscore or
  dash characters and cannot begin or end with a dash.
</span>
</li>
<li>
<span>
Lines starting with a hash character "#" are treated as comments and
  ignored.
</span>
</li>
<li>
<span>
Same named sections and section entries override previously loaded
  sections and section entries (this is sometimes referred to as
  <em>cascading</em>).  Consequently, downstream configuration files need
  only contain those sections and section entries that need to be
  overridden.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/tip.png" alt="Tip" />
</td>
<td class="content">When creating custom configuration files you only need to include
the sections and entries that differ from the default configuration.</td>
</tr></table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/tip.png" alt="Tip" />
</td>
<td class="content">The best way to learn about configuration files is to read the
default configuration files in the AsciiDoc distribution in
conjunction with <tt>asciidoc(1)</tt> output files. You can view configuration
file load sequence by turning on the <tt>asciidoc(1)</tt> <tt>-v</tt> (<tt>--verbose</tt>)
command-line option.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>AsciiDoc reserves the following section names for specific purposes:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
miscellaneous
</dt>
<dd>
<p>
        Configuration options that don&#8217;t belong anywhere else.
</p>
</dd>
<dt class="hdlist1">
attributes
</dt>
<dd>
<p>
        Attribute name/value entries.
</p>
</dd>
<dt class="hdlist1">
specialcharacters
</dt>
<dd>
<p>
        Special characters reserved by the backend markup.
</p>
</dd>
<dt class="hdlist1">
tags
</dt>
<dd>
<p>
        Backend markup tags.
</p>
</dd>
<dt class="hdlist1">
quotes
</dt>
<dd>
<p>
        Definitions for quoted inline character formatting.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
specialwords
</dt>
<dd>
<p>
        Lists of words and phrases singled out for special markup.
</p>
</dd>
<dt class="hdlist1">
replacements, replacements2
</dt>
<dd>
<p>
        Find and replace substitution definitions.
</p>
</dd>
<dt class="hdlist1">
specialsections
</dt>
<dd>
<p>
        Used to single out special section names for specific markup.
&lt;&lt;&lt;
</p>
</dd>
<dt class="hdlist1">
macros
</dt>
<dd>
<p>
        Macro syntax definitions.
</p>
</dd>
<dt class="hdlist1">
titles
</dt>
<dd>
<p>
        Heading, section and block title definitions.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
paradef-*
</dt>
<dd>
<p>
        Paragraph element definitions.
</p>
</dd>
<dt class="hdlist1">
blockdef-*
</dt>
<dd>
<p>
        DelimitedBlock element definitions.
</p>
</dd>
<dt class="hdlist1">
listdef-*
</dt>
<dd>
<p>
        List element definitions.
</p>
</dd>
<dt class="hdlist1">
listtags-*
</dt>
<dd>
<p>
        List element tag definitions.
</p>
</dd>
<dt class="hdlist1">
tabledef-*
</dt>
<dd>
<p>
        Table element definitions.
</p>
</dd>
<dt class="hdlist1">
tabletags-*
</dt>
<dd>
<p>
        Table element tag definitions.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Each line of text in these sections is a <em>section entry</em>. Section
entries share the following syntax:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
name=value
</dt>
<dd>
<p>
        The entry value is set to value.
</p>
</dd>
<dt class="hdlist1">
name=
</dt>
<dd>
<p>
        The entry value is set to a zero length string.
</p>
</dd>
<dt class="hdlist1">
name!
</dt>
<dd>
<p>
        The entry is undefined (deleted from the configuration). This
        syntax only applies to <em>attributes</em> and <em>miscellaneous</em>
        sections.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="title">Section entry behavior</div><ul class="">
<li>
<span>
All equals characters inside the <tt>name</tt> must be escaped with a
  backslash character.
</span>
</li>
<li>
<span>
<tt>name</tt> and <tt>value</tt> are stripped of leading and trailing white space.
</span>
</li>
<li>
<span>
Attribute names, tag entry names and markup template section names
  consist of one or more alphanumeric, underscore or dash characters.
  Names should not begin or end with a dash.
</span>
</li>
<li>
<span>
A blank configuration file section (one without any entries) deletes
  any preceding section with the same name (applies to non-markup
  template sections).
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_miscellaneous_section">26.2. Miscellaneous section</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="26.2. Miscellaneous section";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The optional <tt>[miscellaneous]</tt> section specifies the following
<tt>name=value</tt> options:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
newline
</dt>
<dd>
<p>
        Output file line termination characters. Can include any
        valid Python string escape sequences. The default value is
        <tt>\r\n</tt> (carriage return, line feed). Should not be quoted or
        contain explicit spaces (use <tt>\x20</tt> instead). For example:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -a 'newline=\n' -b docbook mydoc.txt</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
outfilesuffix
</dt>
<dd>
<p>
        The default extension for the output file, for example
        <tt>outfilesuffix=.html</tt>. Defaults to backend name.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
tabsize
</dt>
<dd>
<p>
        The number of spaces to expand tab characters, for example
        <tt>tabsize=4</tt>. Defaults to 8. A <em>tabsize</em> of zero suppresses tab
        expansion (useful when piping included files through block
        filters). Included files can override this option using the
        <em>tabsize</em> attribute.
</p>
</dd>
<dt class="hdlist1">
pagewidth, pageunits
</dt>
<dd>
<p>
        These global table related options are documented in the
        <a href="#X4">Table Configuration File Definitions</a> sub-section.
</p>
</dd>
</dl></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content"><tt>[miscellaneous]</tt> configuration file entries can be set using
the <tt>asciidoc(1)</tt> <tt>-a</tt> (<tt>--attribute</tt>) command-line option.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_titles_section">26.3. Titles section</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="26.3. Titles section";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="dlist"><dl class="">
<dt class="hdlist1">
sectiontitle
</dt>
<dd>
<p>
        Two line section title pattern. The entry value is a Python
        regular expression containing the named group <em>title</em>.
</p>
</dd>
<dt class="hdlist1">
underlines
</dt>
<dd>
<p>
        A comma separated list of document and section title underline
        character pairs starting with the section level 0 and ending
        with section level 4 underline. The default setting is:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>underlines="==","--","~~","^^","++"</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
sect0&#8230;sect4
</dt>
<dd>
<p>
        One line section title patterns. The entry value is a Python
        regular expression containing the named group <em>title</em>.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
blocktitle
</dt>
<dd>
<p>
        <a href="#X42">BlockTitle element</a> pattern.  The entry value is a
        Python regular expression containing the named group <em>title</em>.
</p>
</dd>
<dt class="hdlist1">
subs
</dt>
<dd>
<p>
        A comma separated list of substitutions that are performed on
        the document header and section titles. Defaults to <em>normal</em>
        substitution.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_tags_section">26.4. Tags section</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="26.4. Tags section";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <tt>[tags]</tt> section contains backend tag definitions (one per
line). Tags are used to translate AsciiDoc elements to backend
markup.</p>
</div>
<div class="paragraph">
<p>An AsciiDoc tag definition is formatted like
<tt>&lt;tagname&gt;=&lt;starttag&gt;|&lt;endtag&gt;</tt>. For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>emphasis=&lt;em&gt;|&lt;/em&gt;</tt></pre>
</div></div>
<div class="paragraph">
<p>In this example <tt>asciidoc(1)</tt> replaces the | character with the
emphasized text from the AsciiDoc input file and writes the result to
the output file.</p>
</div>
<div class="paragraph">
<p>Use the <tt>{brvbar}</tt> attribute reference if you need to include a | pipe
character inside tag text.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_attributes_section">26.5. Attributes section</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="26.5. Attributes section";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The optional <tt>[attributes]</tt> section contains predefined attributes.</p>
</div>
<div class="paragraph">
<p>If the attribute value requires leading or trailing spaces then the
text text should be enclosed in quotation mark (") characters.</p>
</div>
<div class="paragraph">
<p>To delete a attribute insert a <tt>name!</tt> entry in a downstream
configuration file or use the <tt>asciidoc(1)</tt> <tt>--attribute name!</tt>
command-line option (an attribute name suffixed with a <tt>!</tt> character
deletes the attribute)</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_special_characters_section">26.6. Special Characters section</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="26.6. Special Characters section";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <tt>[specialcharacters]</tt> section specifies how to escape characters
reserved by the backend markup. Each translation is specified on a
single line formatted like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>&lt;special_character&gt;=&lt;translated_characters&gt;</tt></pre>
</div></div>
<div class="paragraph">
<p>Special characters are normally confined to those that resolve
markup ambiguity (in the case of HTML and XML markups the ampersand,
less than and greater than characters).  The following example causes
all occurrences of the <tt>&lt;</tt> character to be replaced by <tt>&amp;lt;</tt>.</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>&lt;=&amp;lt;</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_quoted_text_section">26.7. Quoted Text section</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="26.7. Quoted Text section";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Quoting is used primarily for text formatting.  The <tt>[quotes]</tt> section
defines AsciiDoc quoting characters and their corresponding backend
markup tags.  Each section entry value is the name of a of a <tt>[tags]</tt>
section entry. The entry name is the character (or characters) that
quote the text.  The following examples are taken from AsciiDoc
configuration files:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[quotes]
_=emphasis</tt></pre>
</div></div>
<div class="literalblock">
<div class="content">
<pre><tt>[tags]
emphasis=&lt;em&gt;|&lt;/em&gt;</tt></pre>
</div></div>
<div class="paragraph">
<p>You can specify the left and right quote strings separately by
separating them with a | character, for example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>``|''=quoted</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Omitting the tag will disable quoting, for example, if you don&#8217;t want
superscripts or subscripts put the following in a custom configuration
file or edit the global <tt>asciidoc.conf</tt> configuration file:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[quotes]
^=
~=</tt></pre>
</div></div>
<div class="paragraph">
<p><a href="#X52">Unconstrained quotes</a> are differentiated from constrained
quotes by prefixing the tag name with a hash character, for example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>__=#emphasis</tt></pre>
</div></div>
<div class="title">Quoted text behavior</div><ul class="">
<li>
<span>
Quote characters must be non-alphanumeric.
</span>
</li>
<li>
<span>
To minimize quoting ambiguity try not to use the same quote
  characters in different quote types.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_special_words_section">26.8. Special Words section</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="26.8. Special Words section";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <tt>[specialwords]</tt> section is used to single out words and phrases
that you want to consistently format in some way throughout your
document without having to repeatedly specify the markup. The name of
each entry corresponds to a markup template section and the entry
value consists of a list of words and phrases to be marked up. For
example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[specialwords]
strongwords=NOTE IMPORTANT</tt></pre>
</div></div>
<div class="literalblock">
<div class="content">
<pre><tt>[strongwords]
&lt;strong&gt;{words}&lt;/strong&gt;</tt></pre>
</div></div>
<div class="paragraph">
<p>The examples specifies that any occurrence of <tt>NOTE</tt> or <tt>IMPORTANT</tt>
should appear in a bold font.</p>
</div>
<div class="paragraph">
<p>Words and word phrases are treated as Python regular expressions: for
example, the word <tt>^NOTE</tt> would only match <tt>NOTE</tt> if appeared at
the start of a line.</p>
</div>
<div class="paragraph">
<p>AsciiDoc comes with three built-in Special Word types:
<em>emphasizedwords</em>, <em>monospacedwords</em> and <em>strongwords</em>, each has a
corresponding (backend specific) markup template section. Edit the
configuration files to customize existing Special Words and to add new
ones.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="title">Special word behavior</div><ul class="">
<li>
<span>
Word list entries must be separated by space characters.
</span>
</li>
<li>
<span>
Word list entries with embedded spaces should be enclosed in quotation (")
  characters.
</span>
</li>
<li>
<span>
A <tt>[specialwords]</tt> section entry of the form
  <tt>name=word1&#160;[word2&#8230;]</tt> adds words to existing <tt>name</tt> entries.
</span>
</li>
<li>
<span>
A <tt>[specialwords]</tt> section entry of the form <tt>name</tt> undefines
  (deletes) all existing <tt>name</tt> words.
</span>
</li>
<li>
<span>
Since word list entries are processed as Python regular expressions
  you need to be careful to escape regular expression special
  characters.
</span>
</li>
<li>
<span>
By default Special Words are substituted before Inline Macros, this
  may lead to undesirable consequences. For example the special word
  <tt>foobar</tt> would be expanded inside the macro call
  <tt>http://www.foobar.com[]</tt>.  A possible solution is to emphasize
  whole words only by defining the word using regular expression
  characters, for example <tt>\bfoobar\b</tt>.
</span>
</li>
<li>
<span>
If the first matched character of a special word is a backslash then
  the remaining characters are output without markup i.e. the
  backslash can be used to escape special word markup.  For example
  the special word <tt>\\?\b[Tt]en\b</tt> will mark up the words <tt>Ten</tt> and
  <tt>ten</tt> only if they are not preceded by a backslash.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X10">26.9. Replacements section</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="26.9. Replacements section";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p><tt>[replacements]</tt> and <tt>[replacements2]</tt> configuration file entries
specify find and replace text and are formatted like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>&lt;find_pattern&gt;=&lt;replacement_text&gt;</tt></pre>
</div></div>
<div class="paragraph">
<p>The find text can be a Python regular expression; the replace text can
contain Python regular expression group references.</p>
</div>
<div class="paragraph">
<p>Use Replacement shortcuts for often used macro references, for
example (the second replacement allows us to backslash escape the
macro name):</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>NEW!=image:./images/smallnew.png[New!]
\\NEW!=NEW!</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="title">Replacement behavior</div><ul class="">
<li>
<span>
The built-in replacements can be escaped with a backslash.
</span>
</li>
<li>
<span>
If the find or replace text has leading or trailing spaces then the
  text should be enclosed in quotation (") characters.
</span>
</li>
<li>
<span>
Since the find text is processed as a regular expression you need to
  be careful to escape regular expression special characters.
</span>
</li>
<li>
<span>
Replacements are performed in the same order they appear in the
  configuration file replacements section.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_markup_template_sections">26.10. Markup Template Sections</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="26.10. Markup Template Sections";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Markup template sections supply backend markup for translating
AsciiDoc elements.  Since the text is normally backend dependent
you&#8217;ll find these sections in the backend specific configuration
files. Template sections differ from other sections in that they
contain a single block of text instead of per line <em>name=value</em>
entries. A markup template section body can contain:</p>
</div>
<ul class="">
<li>
<span>
Attribute references
</span>
</li>
<li>
<span>
System macro calls.
</span>
</li>
<li>
<span>
A document content placeholder
</span>
</li>
</ul>
<div class="paragraph">
<p>The document content placeholder is a single | character and is
replaced by text from the source element.  Use the <tt>{brvbar}</tt>
attribute reference if you need a literal | character in the template.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X27">26.11. Configuration file names, precedence and locations</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="26.11. Configuration file names, precedence and locations";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Configuration files have a <tt>.conf</tt> file name extension; they are
loaded from the following locations:</p>
</div>
<ol class="arabic">
<li>
<span>
The directory containing the asciidoc executable.
</span>
</li>
<li>
<span>
If there is no <tt>asciidoc.conf</tt> file in the directory containing the
   asciidoc executable then load from the global configuration
   directory (normally <tt>/etc/asciidoc</tt> or <tt>/usr/local/etc/asciidoc</tt>)
   i.e. the global configuration files directory is skipped if
   AsciiDoc configuration files are installed in the same directory as
   the asciidoc executable. This allows both a system wide copy and
   multiple local copies of AsciiDoc to coexist on the same host PC.
</span>
</li>
<li>
<span>
The user&#8217;s <tt>$HOME/.asciidoc</tt> directory (if it exists).
</span>
</li>
<li>
<span>
The directory containing the AsciiDoc source file.
</span>
</li>
<li>
<span>
Explicit configuration files specified using:
</span>
<ul class="">
<li>
<span>
The <tt>conf-files</tt> attribute (one or more file names separated by a
     <tt>|</tt> character). These files are loaded in the order they are
     specified and prior to files specified using the <tt>--conf-file</tt>
     command-line option.
</span>
</li>
<li>
<span>
The <tt>asciidoc(1)</tt> <tt>--conf-file</tt>) command-line option.  The
     <tt>--conf-file</tt> option can be specified multiple times, in which
     case configuration files will be processed in the same order they
     appear on the command-line.
</span>
</li>
</ul>
</li>
<li>
<span>
<a href="#X100">Backend plugin</a> configuration files are loaded from
   subdirectories named like <tt>backends/&lt;backend&gt;</tt> in locations 1, 2
   and 3.
</span>
</li>
</ol>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Configuration files from the above locations are loaded in the
following order:</p>
</div>
<ul class="">
<li>
<span>
The <tt>[attributes]</tt> section only from:
</span>
<ul class="">
<li>
<span>
<tt>asciidoc.conf</tt> in location 3
</span>
</li>
<li>
<span>
Files from location 5.
</span>
<div class="paragraph">
<p>This first pass makes locally set attributes available in the global
<tt>asciidoc.conf</tt> file.</p>
</div>
</li>
</ul>
</li>
<li>
<span>
<tt>asciidoc.conf</tt> from locations 1, 2, 3.
</span>
</li>
<li>
<span>
<em>attributes</em>, <em>titles</em> and <em>specialcharacters</em> sections from the
  <tt>asciidoc.conf</tt> in location 4.
</span>
</li>
<li>
<span>
The document header is parsed at this point and we can assume the
  <em>backend</em> and <em>doctype</em> have now been defined.
</span>
</li>
<li>
<span>
Backend plugin <tt>&lt;backend&gt;.conf</tt> and <tt>&lt;backend&gt;-&lt;doctype&gt;.conf</tt> files
  from locations 6.  If a backend plugin is not found then try
  locations 1, 2 and 3 for <tt>&lt;backend&gt;.conf</tt> and
  <tt>&lt;backend&gt;-&lt;doctype&gt;.conf</tt> backend configuration files.
</span>
</li>
<li>
<span>
Filter conf files from the <tt>filters</tt> directory in locations 1, 2, 3.
</span>
</li>
<li>
<span>
<tt>lang-&lt;lang&gt;.conf</tt> from locations 1, 2, 3.
</span>
</li>
<li>
<span>
<tt>asciidoc.conf</tt> from location 4.
</span>
</li>
<li>
<span>
<tt>&lt;backend&gt;.conf</tt> and <tt>&lt;backend&gt;-&lt;doctype&gt;.conf</tt> from location 4.
  2,3.
</span>
</li>
<li>
<span>
Filter conf files from location 4.
</span>
</li>
<li>
<span>
<tt>&lt;docfile&gt;.conf</tt> and <tt>&lt;docfile&gt;-&lt;backend&gt;.conf</tt> from location 4.
</span>
</li>
<li>
<span>
Configuration files from location 5.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Where:</p>
</div>
<ul class="">
<li>
<span>
<tt>&lt;backend&gt;</tt> and <tt>&lt;doctype&gt;</tt> are values specified by the <tt>asciidoc(1)</tt>
  <tt>-b</tt> (<tt>--backend</tt>) and <tt>-d</tt> (<tt>--doctype</tt>) command-line options.
</span>
</li>
<li>
<span>
<tt>&lt;infile&gt;</tt> is the path name of the AsciiDoc input file without the
  file name extension.
</span>
</li>
<li>
<span>
<tt>&lt;lang&gt;</tt> is a two letter country code set by the the AsciiDoc <em>lang</em>
  attribute.
</span>
</li>
</ul>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">
<div class="paragraph">
<p>The backend and language global configuration files are loaded <strong>after</strong>
the header has been parsed.  This means that you can set most
attributes in the document header. Here&#8217;s an example header:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>Life's Mysteries
================
:author: Hu Nose
:doctype: book
:toc:
:icons:
:data-uri:
:lang: en
:encoding: iso-8859-1</tt></pre>
</div></div>
<div class="paragraph">
<p>Attributes set in the document header take precedence over
configuration file attributes.</p>
</div>
</td>
</tr></table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/tip.png" alt="Tip" />
</td>
<td class="content">Use the <tt>asciidoc(1)</tt> <tt>-v</tt> (<tt>--verbose</tt>) command-line option to see
which configuration files are loaded and the order in which they are
loaded.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_document_attributes">27. Document Attributes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="27. Document Attributes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>A document attribute is comprised of a <em>name</em> and a textual <em>value</em>
and is used for textual substitution in AsciiDoc documents and
configuration files. An attribute reference (an attribute name
enclosed in braces) is replaced by the corresponding attribute
value. Attribute names are case insensitive and can only contain
alphanumeric, dash and underscore characters.</p>
</div>
<div class="paragraph">
<p>There are four sources of document attributes (from highest to lowest
precedence):</p>
</div>
<ul class="">
<li>
<span>
Command-line attributes.
</span>
</li>
<li>
<span>
AttributeEntry, AttributeList, Macro and BlockId elements.
</span>
</li>
<li>
<span>
Configuration file <tt>[attributes]</tt> sections.
</span>
</li>
<li>
<span>
Intrinsic attributes.
</span>
</li>
</ul>
<div class="paragraph">
<p>Within each of these divisions the last processed entry takes
precedence.</p>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">If an attribute is not defined then the line containing the
attribute reference is dropped. This property is used extensively in
AsciiDoc configuration files to facilitate conditional markup
generation.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X18">28. Attribute Entries</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="28. Attribute Entries";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <tt>AttributeEntry</tt> block element allows document attributes to be
assigned within an AsciiDoc document. Attribute entries are added to
the global document attributes dictionary. The attribute name/value
syntax is a single line like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>:&lt;name&gt;: &lt;value&gt;</tt></pre>
</div></div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>:Author Initials: JB</tt></pre>
</div></div>
<div class="paragraph">
<p>This will set an attribute reference <tt>{authorinitials}</tt> to the value
<em>JB</em> in the current document.</p>
</div>
<div class="paragraph">
<p>To delete (undefine) an attribute use the following syntax:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>:&lt;name&gt;!:</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="title">AttributeEntry behavior</div><ul class="">
<li>
<span>
The attribute entry line begins with colon&#8201;&#8212;&#8201;no white space allowed
  in left margin.
</span>
</li>
<li>
<span>
AsciiDoc converts the <tt>&lt;name&gt;</tt> to a legal attribute name (lower
  case, alphanumeric, dash and underscore characters only&#8201;&#8212;&#8201;all other
  characters deleted). This allows more human friendly text to be
  used.
</span>
</li>
<li>
<span>
Leading and trailing white space is stripped from the <tt>&lt;value&gt;</tt>.
</span>
</li>
<li>
<span>
Lines ending in a space followed by a plus character are continued
  to the next line, for example:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>:description: AsciiDoc is a text document format for writing notes, +
              documentation, articles, books, slideshows, web pages +
              and man pages.</tt></pre>
</div></div>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<ul class="">
<li>
<span>
If the <tt>&lt;value&gt;</tt> is blank then the corresponding attribute value is
  set to an empty string.
</span>
</li>
<li>
<span>
Attribute references contained in the entry <tt>&lt;value&gt;</tt> will be
  expanded.
</span>
</li>
<li>
<span>
By default AttributeEntry values are substituted for
  <tt>specialcharacters</tt> and <tt>attributes</tt> (see above), if you want to
  change or disable AttributeEntry substitution use the <a href="#X77">   inline macro</a> syntax.
</span>
</li>
<li>
<span>
Attribute entries in the document Header are available for header
  markup template substitution.
</span>
</li>
<li>
<span>
Attribute elements override configuration file and intrinsic
  attributes but do not override command-line attributes.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Here are some more attribute entry examples:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>AsciiDoc User Manual
====================
:author:    Stuart Rackham
:email:     srackham@gmail.com
:revdate:   April 23, 2004
:revnumber: 5.1.1</tt></pre>
</div></div>
<div class="paragraph">
<p>Which creates these attributes:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>{author}, {firstname}, {lastname}, {authorinitials}, {email},
{revdate}, {revnumber}</tt></pre>
</div></div>
<div class="paragraph">
<p>The previous example is equivalent to this <a href="#X95">document header</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>AsciiDoc User Manual
====================
Stuart Rackham &lt;srackham@gmail.com&gt;
5.1.1, April 23, 2004</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_setting_configuration_entries">28.1. Setting configuration entries</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="28.1. Setting configuration entries";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>A variant of the Attribute Entry syntax allows configuration file
section entries and markup template sections to be set from within an
AsciiDoc document:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>:&lt;section_name&gt;.[&lt;entry_name&gt;]: &lt;entry_value&gt;</tt></pre>
</div></div>
<div class="paragraph">
<p>Where <tt>&lt;section_name&gt;</tt> is the configuration section name,
<tt>&lt;entry_name&gt;</tt> is the name of the entry and <tt>&lt;entry_value&gt;</tt> is the
optional entry value. This example sets the default labeled list
style to <em>horizontal</em>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>:listdef-labeled.style: horizontal</tt></pre>
</div></div>
<div class="paragraph">
<p>It is exactly equivalent to a configuration file containing:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[listdef-labeled]
style=horizontal</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<ul class="">
<li>
<span>
If the <tt>&lt;entry_name&gt;</tt> is omitted then the entire section is
  substituted with the <tt>&lt;entry_value&gt;</tt>. This feature should only be
  used to set markup template sections. The following example sets the
  <em>xref2</em> inline macro markup template:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>:xref2-inlinemacro.: &lt;a href="#{1}"&gt;{2?{2}}&lt;/a&gt;</tt></pre>
</div></div>
</li>
<li>
<span>
No substitution is performed on configuration file attribute entries
  and they cannot be undefined.
</span>
</li>
<li>
<span>
This feature can only be used in attribute entries&#8201;&#8212;&#8201;configuration
  attributes cannot be set using the <tt>asciidoc(1)</tt> command <tt>--attribute</tt>
  option.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="sidebarblock" id="X62">
<div class="content">
<div class="title">Attribute entries promote clarity and eliminate repetition</div>
<div class="paragraph">
<p>URLs and file names in AsciiDoc macros are often quite long&#8201;&#8212;&#8201;they
break paragraph flow and readability suffers.  The problem is
compounded by redundancy if the same name is used repeatedly.
Attribute entries can be used to make your documents easier to read
and write, here are some examples:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>:1:         http://freshmeat.net/projects/asciidoc/
:homepage:  http://methods.co.nz/asciidoc/[AsciiDoc home page]
:new:       image:./images/smallnew.png[]
:footnote1: footnote:[A meaningless latin term]</tt></pre>
</div></div>
<div class="literalblock">
<div class="content">
<pre><tt>Using previously defined attributes: See the {1}[Freshmeat summary]
or the {homepage} for something new {new}. Lorem ispum {footnote1}.</tt></pre>
</div></div>
<div class="title">Note</div><ul class="">
<li>
<span>
The attribute entry definition must precede it&#8217;s usage.
</span>
</li>
<li>
<span>
You are not limited to URLs or file names, entire macro calls or
  arbitrary lines of text can be abbreviated.
</span>
</li>
<li>
<span>
Shared attributes entries could be grouped into a separate file and
  <a href="#X63">included</a> in multiple documents.
</span>
</li>
</ul>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X21">29. Attribute Lists</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="29. Attribute Lists";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<ul class="">
<li>
<span>
An attribute list is a comma separated list of attribute values.
</span>
</li>
<li>
<span>
The entire list is enclosed in square brackets.
</span>
</li>
<li>
<span>
Attribute lists are used to pass parameters to macros, blocks (using
  the <a href="#X79">AttributeList element</a>) and inline quotes.
</span>
</li>
</ul>
<div class="paragraph">
<p>The list consists of zero or more positional attribute values followed
by zero or more named attribute values.  Here are three examples: a
single unquoted positional attribute; three unquoted positional
attribute values; one positional attribute followed by two named
attributes; the unquoted attribute value in the final example contains
comma (<tt>&amp;#44;</tt>) and double-quote (<tt>&amp;#34;</tt>) character entities:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>[Hello]
[quote, Bertrand Russell, The World of Mathematics (1956)]
["22 times", backcolor="#0e0e0e", options="noborders,wide"]
[A footnote&amp;#44; &amp;#34;with an image&amp;#34; image:smallnew.png[]]</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="title">Attribute list behavior</div><ul class="">
<li>
<span>
If one or more attribute values contains a comma the all string
  values must be quoted (enclosed in double quotation mark
  characters).
</span>
</li>
<li>
<span>
If the list contains any named or quoted attributes then all string
  attribute values must be quoted.
</span>
</li>
<li>
<span>
To include a double quotation mark (") character in a quoted
  attribute value the the quotation mark must be escaped with a
  backslash.
</span>
</li>
<li>
<span>
List attributes take precedence over existing attributes.
</span>
</li>
<li>
<span>
List attributes can only be referenced in configuration file markup
  templates and tags, they are not available elsewhere in the
  document.
</span>
</li>
<li>
<span>
Setting a named attribute to <tt>None</tt> undefines the attribute.
</span>
</li>
<li>
<span>
Positional attributes are referred to as <tt>{1}</tt>,<tt>{2}</tt>,<tt>{3}</tt>,&#8230;
</span>
</li>
<li>
<span>
Attribute <tt>{0}</tt> refers to the entire list (excluding the enclosing
  square brackets).
</span>
</li>
<li>
<span>
Named attribute names cannot contain dash characters.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X75">29.1. Options attribute</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="29.1. Options attribute";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>If the attribute list contains an attribute named <tt>options</tt> it is
processed as a comma separated list of option names:</p>
</div>
<ul class="">
<li>
<span>
Each name generates an attribute named like <tt>&lt;option&gt;-option</tt> (where
  <tt>&lt;option&gt;</tt> is the option name) with an empty string value.  For
  example <tt>[options="opt1,opt2,opt3"]</tt> is equivalent to setting the
  following three attributes
  <tt>[opt1-option="",opt2-option="",opt2-option=""]</tt>.
</span>
</li>
<li>
<span>
If you define a an option attribute globally (for example with an
  <a href="#X18">attribute entry</a>) then it will apply to all elements in the
  document.
</span>
</li>
<li>
<span>
AsciiDoc implements a number of predefined options which are listed
  in the <a href="#X74">Attribute Options appendix</a>.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_macro_attribute_lists">29.2. Macro Attribute lists</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="29.2. Macro Attribute lists";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Macros calls are suffixed with an attribute list. The list may be
empty but it cannot be omitted. List entries are used to pass
attribute values to macro markup templates.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_attribute_references">30. Attribute References</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="30. Attribute References";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>An attribute reference is an attribute name (possibly followed by an
additional parameters) enclosed in curly braces.  When an attribute
reference is encountered it is evaluated and replaced by its
corresponding text value.  If the attribute is undefined the line
containing the attribute is dropped.</p>
</div>
<div class="paragraph">
<p>There are three types of attribute reference: <em>Simple</em>, <em>Conditional</em>
and <em>System</em>.</p>
</div>
<div class="title">Attribute reference evaluation</div><ul class="">
<li>
<span>
You can suppress attribute reference expansion by placing a
  backslash character immediately in front of the opening brace
  character.
</span>
</li>
<li>
<span>
By default attribute references are not expanded in
  <em>LiteralParagraphs</em>, <em>ListingBlocks</em> or <em>LiteralBlocks</em>.
</span>
</li>
<li>
<span>
Attribute substitution proceeds line by line in reverse line order.
</span>
</li>
<li>
<span>
Attribute reference evaluation is performed in the following order:
  <em>Simple</em> then <em>Conditional</em> and finally <em>System</em>.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_simple_attributes_references">30.1. Simple Attributes References</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="30.1. Simple Attributes References";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Simple attribute references take the form <tt>{&lt;name&gt;}</tt>. If the
attribute name is defined its text value is substituted otherwise the
line containing the reference is dropped from the output.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_conditional_attribute_references">30.2. Conditional Attribute References</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="30.2. Conditional Attribute References";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Additional parameters are used in conjunction with attribute names to
calculate a substitution value. Conditional attribute references take
the following forms:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
<tt>{&lt;names&gt;=&lt;value&gt;}</tt>
</dt>
<dd>
<p>
        <tt>&lt;value&gt;</tt> is substituted if the attribute <tt>&lt;names&gt;</tt> is
        undefined otherwise its value is substituted. <tt>&lt;value&gt;</tt> can
        contain simple attribute references.
</p>
</dd>
<dt class="hdlist1">
<tt>{&lt;names&gt;?&lt;value&gt;}</tt>
</dt>
<dd>
<p>
        <tt>&lt;value&gt;</tt> is substituted if the attribute <tt>&lt;names&gt;</tt> is defined
        otherwise an empty string is substituted.  <tt>&lt;value&gt;</tt> can
        contain simple attribute references.
</p>
</dd>
<dt class="hdlist1">
<tt>{&lt;names&gt;!&lt;value&gt;}</tt>
</dt>
<dd>
<p>
        <tt>&lt;value&gt;</tt> is substituted if the attribute <tt>&lt;names&gt;</tt> is
        undefined otherwise an empty string is substituted.  <tt>&lt;value&gt;</tt>
        can contain simple attribute references.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
<tt>{&lt;names&gt;#&lt;value&gt;}</tt>
</dt>
<dd>
<p>
        <tt>&lt;value&gt;</tt> is substituted if the attribute <tt>&lt;names&gt;</tt> is defined
        otherwise the undefined attribute entry causes the containing
        line to be dropped.  <tt>&lt;value&gt;</tt> can contain simple attribute
        references.
</p>
</dd>
<dt class="hdlist1">
<tt>{&lt;names&gt;%&lt;value&gt;}</tt>
</dt>
<dd>
<p>
        <tt>&lt;value&gt;</tt> is substituted if the attribute <tt>&lt;names&gt;</tt> is not
        defined otherwise the containing line is dropped.  <tt>&lt;value&gt;</tt>
        can contain simple attribute references.
</p>
</dd>
<dt class="hdlist1">
<tt>{&lt;names&gt;@&lt;regexp&gt;:&lt;value1&gt;[:&lt;value2&gt;]}</tt>
</dt>
<dd>
<p>
        <tt>&lt;value1&gt;</tt> is substituted if the value of attribute <tt>&lt;names&gt;</tt>
        matches the regular expression <tt>&lt;regexp&gt;</tt> otherwise <tt>&lt;value2&gt;</tt>
        is substituted. If attribute <tt>&lt;names&gt;</tt> is not defined the
        containing line is dropped. If <tt>&lt;value2&gt;</tt> is omitted an empty
        string is assumed. The values and the regular expression can
        contain simple attribute references.  To embed colons in the
        values or the regular expression escape them with backslashes.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
<tt>{&lt;names&gt;$&lt;regexp&gt;:&lt;value1&gt;[:&lt;value2&gt;]}</tt>
</dt>
<dd>
<p>
        Same behavior as the previous ternary attribute except for
        the following cases:
</p>
<div class="dlist"><dl class="">
<dt class="hdlist1">
<tt>{&lt;names&gt;$&lt;regexp&gt;:&lt;value&gt;}</tt>
</dt>
<dd>
<p>
                Substitutes <tt>&lt;value&gt;</tt> if <tt>&lt;names&gt;</tt> matches <tt>&lt;regexp&gt;</tt>
                otherwise the result is undefined and the containing
                line is dropped.
</p>
</dd>
<dt class="hdlist1">
<tt>{&lt;names&gt;$&lt;regexp&gt;::&lt;value&gt;}</tt>
</dt>
<dd>
<p>
                Substitutes <tt>&lt;value&gt;</tt> if <tt>&lt;names&gt;</tt> does not match
                <tt>&lt;regexp&gt;</tt> otherwise the result is undefined and the
                containing line is dropped.
</p>
</dd>
</dl></div>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>The attribute <tt>&lt;names&gt;</tt> parameter normally consists of a single
attribute name but it can be any one of the following:</p>
</div>
<ul class="">
<li>
<span>
A single attribute name which evaluates to the attributes value.
</span>
</li>
<li>
<span>
Multiple <em>,</em> separated attribute names which evaluates to an empty
  string if one or more of the attributes is defined, otherwise it&#8217;s
  value is undefined.
</span>
</li>
<li>
<span>
Multiple <em>+</em> separated attribute names which evaluates to an empty
  string if all of the attributes are defined, otherwise it&#8217;s value is
  undefined.
</span>
</li>
</ul>
<div class="paragraph">
<p>Conditional attributes with single attribute names are evaluated first
so they can be used inside the multi-attribute conditional <tt>&lt;value&gt;</tt>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="_conditional_attribute_examples">30.2.1. Conditional attribute examples</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="30.2.1. Conditional attribute examples";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Conditional attributes are mainly used in AsciiDoc configuration
files&#8201;&#8212;&#8201;see the distribution <tt>.conf</tt> files for examples.</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
Attribute equality test
</dt>
<dd>
<p>
  If <tt>{backend}</tt> is <em>docbook45</em> or <em>xhtml11</em> the example evaluates to
  &#8220;DocBook 4.5 or XHTML 1.1 backend&#8221; otherwise it evaluates to
  &#8220;some other backend&#8221;:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>{backend@docbook45|xhtml11:DocBook 4.5 or XHTML 1.1 backend:some other backend}</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
Attribute value map
</dt>
<dd>
<p>
  This example maps the <tt>frame</tt> attribute values [<tt>topbot</tt>, <tt>all</tt>,
  <tt>none</tt>, <tt>sides</tt>] to [<tt>hsides</tt>, <tt>border</tt>, <tt>void</tt>, <tt>vsides</tt>]:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>{frame@topbot:hsides}{frame@all:border}{frame@none:void}{frame@sides:vsides}</tt></pre>
</div></div>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X24">30.3. System Attribute References</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="30.3. System Attribute References";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>System attribute references generate the attribute text value by
executing a predefined action that is parametrized by one or more
arguments. The syntax is <tt>{&lt;action&gt;:&lt;arguments&gt;}</tt>.</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
<tt>{counter:&lt;attrname&gt;[:&lt;seed&gt;]}</tt>
</dt>
<dd>
<p>
        Increments the document attribute (if the attribute is
        undefined it is set to <tt>1</tt>). Returns the new attribute value.
</p>
<ul class="">
<li>
<span>
Counters generate global (document wide) attributes.
</span>
</li>
<li>
<span>
The optional <tt>&lt;seed&gt;</tt> specifies the counter&#8217;s initial value;
          it can be a number or a single letter; defaults to <em>1</em>.
</span>
</li>
<li>
<span>
<tt>&lt;seed&gt;</tt> can contain simple and conditional attribute
          references.
</span>
</li>
<li>
<span>
The <em>counter</em> system attribute will not be executed if the
          containing line is dropped by the prior evaluation of an
          undefined attribute.
</span>
</li>
</ul>
</dd>
<dt class="hdlist1">
<tt>{counter2:&lt;attrname&gt;[:&lt;seed&gt;]}</tt>
</dt>
<dd>
<p>
        Same as <tt>counter</tt> except the it always returns a blank string.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
<tt>{eval:&lt;expression&gt;}</tt>
</dt>
<dd>
<p>
        Substitutes the result of the Python <tt>&lt;expression&gt;</tt>.
</p>
<ul class="">
<li>
<span>
If <tt>&lt;expression&gt;</tt> evaluates to <tt>None</tt> or <tt>False</tt> the
          reference is deemed undefined and the line containing the
          reference is dropped from the output.
</span>
</li>
<li>
<span>
If the expression evaluates to <tt>True</tt> the attribute
          evaluates to an empty string.
</span>
</li>
<li>
<span>
<tt>&lt;expression&gt;</tt> can contain simple and conditional attribute
          references.
</span>
</li>
<li>
<span>
The <em>eval</em> system attribute can be nested inside other
          system attributes.
</span>
</li>
</ul>
</dd>
<dt class="hdlist1">
<tt>{eval3:&lt;command&gt;}</tt>
</dt>
<dd>
<p>
        Passthrough version of <tt>{eval:&lt;expression&gt;}</tt>&#8201;&#8212;&#8201;the generated
        output is written directly to the output without any further
        substitutions.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
<tt>{include:&lt;filename&gt;}</tt>
</dt>
<dd>
<p>
        Substitutes contents of the file named <tt>&lt;filename&gt;</tt>.
</p>
<ul class="">
<li>
<span>
The included file is read at the time of attribute
          substitution.
</span>
</li>
<li>
<span>
If the file does not exist a warning is emitted and the line
          containing the reference is dropped from the output file.
</span>
</li>
<li>
<span>
Tabs are expanded based on the current <em>tabsize</em> attribute
          value.
</span>
</li>
</ul>
</dd>
<dt class="hdlist1">
<tt>{set:&lt;attrname&gt;[!][:&lt;value&gt;]}</tt>
</dt>
<dd>
<p>
        Sets or unsets document attribute. Normally only used in
        configuration file markup templates (use
        <a href="#X18">AttributeEntries</a> in AsciiDoc documents).
</p>
<ul class="">
<li>
<span>
If the attribute name is followed by an exclamation mark
          the attribute becomes undefined.
</span>
</li>
<li>
<span>
If <tt>&lt;value&gt;</tt> is omitted the attribute is set to a blank
          string.
</span>
</li>
<li>
<span>
<tt>&lt;value&gt;</tt> can contain simple and conditional attribute
          references.
</span>
</li>
<li>
<span>
Returns a blank string unless the attribute is undefined in
          which case the return value is undefined and the enclosing
          line will be dropped.
</span>
</li>
</ul>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
<tt>{set2:&lt;attrname&gt;[!][:&lt;value&gt;]}</tt>
</dt>
<dd>
<p>
        Same as <tt>set</tt> except that the attribute scope is local to the
        template.
</p>
</dd>
<dt class="hdlist1">
<tt>{sys:&lt;command&gt;}</tt>
</dt>
<dd>
<p>
        Substitutes the stdout generated by the execution of the shell
        <tt>&lt;command&gt;</tt>.
</p>
</dd>
<dt class="hdlist1">
<tt>{sys2:&lt;command&gt;}</tt>
</dt>
<dd>
<p>
        Substitutes the stdout and stderr generated by the execution
        of the shell <tt>&lt;command&gt;</tt>.
</p>
</dd>
<dt class="hdlist1">
<tt>{sys3:&lt;command&gt;}</tt>
</dt>
<dd>
<p>
        Passthrough version of <tt>{sys:&lt;command&gt;}</tt>&#8201;&#8212;&#8201;the generated
        output is written directly to the output without any further
        substitutions.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
<tt>{template:&lt;template&gt;}</tt>
</dt>
<dd>
<p>
        Substitutes the contents of the configuration file section
        named <tt>&lt;template&gt;</tt>. Attribute references contained in the
        template are substituted.
</p>
</dd>
</dl></div>
<div class="title">System reference behavior</div><ul class="">
<li>
<span>
System attribute arguments can contain non-system attribute
  references.
</span>
</li>
<li>
<span>
Closing brace characters inside system attribute arguments must be
  escaped with a backslash.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X60">31. Intrinsic Attributes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="31. Intrinsic Attributes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Intrinsic attributes are simple attributes that are created
automatically from: AsciiDoc document header parameters; <tt>asciidoc(1)</tt>
command-line arguments; attributes defined in the default
configuration files; the execution context.  Here&#8217;s the list of
predefined intrinsic attributes:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>{amp}                 ampersand (&amp;) character entity
{asciidoc-args}       used to pass inherited arguments to asciidoc filters
{asciidoc-confdir}    the asciidoc(1) global configuration directory
{asciidoc-dir}        the asciidoc(1) application directory
{asciidoc-file}       the full path name of the asciidoc(1) script
{asciidoc-version}    the version of asciidoc(1)
{author}              author's full name
{authored}            empty string '' if {author} or {email} defined,
{authorinitials}      author initials (from document header)
{backend-&lt;backend&gt;}   empty string ''
{&lt;backend&gt;-&lt;doctype&gt;} empty string ''
{backend}             document backend specified by `-b` option
{backslash}           backslash character
{basebackend-&lt;base&gt;}  empty string ''
{basebackend}         html or docbook</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="literalblock">
<div class="content">
<pre><tt>{brvbar}              broken vertical bar (|) character
{docdate}             document last modified date
{docdir}              document input directory name  (note 5)
{docfile}             document file name  (note 5)
{docname}             document file name without extension (note 6)
{doctime}             document last modified time
{doctitle}            document title (from document header)
{doctype-&lt;doctype&gt;}   empty string ''
{doctype}             document type specified by `-d` option
{email}               author's email address (from document header)
{empty}               empty string ''
{encoding}            specifies input and output encoding
{filetype-&lt;fileext&gt;}  empty string ''
{filetype}            output file name file extension
{firstname}           author first name (from document header)</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="literalblock">
<div class="content">
<pre><tt>{gt}                  greater than (&gt;) character entity
{id}                  running block id generated by BlockId elements
{indir}               input file directory name (note 2,5)
{infile}              input file name (note 2,5)
{lastname}            author last name (from document header)
{ldquo}               Left double quote character (note 7)
{level}               title level 1..4 (in section titles)
{listindex}           the list index (1..) of the most recent list item
{localdate}           the current date
{localtime}           the current time
{lsquo}               Left single quote character (note 7)
{lt}                  less than (&lt;) character entity
{manname}             manpage name (defined in NAME section)
{manpurpose}          manpage (defined in NAME section)
{mantitle}            document title minus the manpage volume number
{manvolnum}           manpage volume number (1..8) (from document header)
{middlename}          author middle name (from document header)
{nbsp}                non-breaking space character entity
{notitle}             do not display the document title</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="literalblock">
<div class="content">
<pre><tt>{outdir}              document output directory name (note 2)
{outfile}             output file name (note 2)
{rdquo}               Right double quote character (note 7)
{reftext}             running block xreflabel generated by BlockId elements
{revdate}             document revision date (from document header)
{revnumber}           document revision number (from document header)
{rsquo}               Right single quote character (note 7)
{sectnum}             formatted section number (in section titles)
{showcomments}        send comment lines to the output
{title}               section title (in titled elements)
{two-colons}          Two colon characters
{two-semicolons}      Two semicolon characters
{user-dir}            the ~/.asciidoc directory (if it exists)
{verbose}             defined as '' if --verbose command option specified
{zwsp}                Zero-width space character entity</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">
<ol class="arabic">
<li>
<span>
Intrinsic attributes are global so avoid defining custom attributes
   with the same names.
</span>
</li>
<li>
<span>
<tt>{outfile}</tt>, <tt>{outdir}</tt>, <tt>{infile}</tt>, <tt>{indir}</tt> attributes are
   effectively read-only (you can set them but it won&#8217;t affect the
   input or output file paths).
</span>
</li>
<li>
<span>
See also the <a href="#X88">Backend Attributes</a> section for attributes
    that relate to AsciiDoc XHTML file generation.
</span>
</li>
<li>
<span>
The entries that translate to blank strings are designed to be used
   for conditional text inclusion. You can also use the <tt>ifdef</tt>,
   <tt>ifndef</tt> and <tt>endif</tt> System macros for conditional inclusion.
   <script type="text/javascript">/*<![CDATA[*/slidefootnotes += "<div class='footnote'>[3] : Conditional inclusion using <tt>ifdef</tt> and <tt>ifndef</tt> macros
   differs from attribute conditional inclusion in that the former
   occurs when the file is read while the latter occurs when the
   contents are written.</div>" ;/*]]>*/</script>
[3]
</span>
</li>
<li>
<span>
<tt>{docfile}</tt> and <tt>{docdir}</tt> refer to root document specified on the
   <tt>asciidoc(1)</tt> command-line; <tt>{infile}</tt> and <tt>{indir}</tt> refer to the
   current input file which may be the root document or an included
   file. When the input is being read from the standard input
   (<tt>stdin</tt>) these attributes are undefined.
</span>
</li>
<li>
<span>
If the input file is the standard input and the output file is not
   the standard output then <tt>{docname}</tt> is the output file name sans
   file extension.
</span>
</li>
<li>
<span>
See
   <a href="http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks">non-English
   usage of quotation marks</a>.
</span>
</li>
</ol>
</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X73">32. Block Element Definitions</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="32. Block Element Definitions";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The syntax and behavior of Paragraph, DelimitedBlock, List and Table
block elements is determined by block definitions contained in
<a href="#X7">AsciiDoc configuration file</a> sections.</p>
</div>
<div class="paragraph">
<p>Each definition consists of a section title followed by one or more
section entries. Each entry defines a block parameter controlling some
aspect of the block&#8217;s behavior. Here&#8217;s an example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[blockdef-listing]
delimiter=^-{4,}$
template=listingblock
presubs=specialcharacters,callouts</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>AsciiDoc Paragraph, DelimitedBlock, List and Table block elements
share a common subset of configuration file parameters:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
delimiter
</dt>
<dd>
<p>
  A Python regular expression that matches the first line of a block
  element&#8201;&#8212;&#8201;in the case of DelimitedBlocks and Tables it also matches
  the last line.
</p>
</dd>
<dt class="hdlist1">
template
</dt>
<dd>
<p>
  The name of the configuration file markup template section that will
  envelope the block contents. The pipe (<em>|</em>) character is substituted
  for the block contents. List elements use a set of (list specific)
  tag parameters instead of a single template. The template name can
  contain attribute references allowing dynamic template selection a
  the time of template substitution.
</p>
</dd>
<dt class="hdlist1">
options
</dt>
<dd>
<p>
  A comma delimited list of element specific option names. In addition
  to being used internally, options are available during markup tag
  and template substitution as attributes with an empty string value
  named like <tt>&lt;option&gt;-option</tt> (where <tt>&lt;option&gt;</tt> is the option name).
  See <a href="#X74">attribute options</a> for a complete list of available
  options.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
subs, presubs, postsubs
</dt>
<dd>
<ul class="">
<li>
<span>
<em>presubs</em> and <em>postsubs</em> are lists of comma separated substitutions that are
    performed on the block contents. <em>presubs</em> is applied first,
    <em>postsubs</em> (if specified) second.
</span>
</li>
<li>
<span>
<em>subs</em> is an alias for <em>presubs</em>.
</span>
</li>
<li>
<span>
If a <em>filter</em> is allowed (Paragraphs, DelimitedBlocks and Tables)
    and has been specified then <em>presubs</em> and <em>postsubs</em> substitutions
    are performed before and after the filter is run respectively.
</span>
</li>
<li>
<span>
Allowed values: <em>specialcharacters</em>, <em>quotes</em>, <em>specialwords</em>,
    <em>replacements</em>, <em>macros</em>, <em>attributes</em>, <em>callouts</em>.
</span>
</li>
</ul>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
subs, presubs, postsubs (2)
</dt>
<dd>
<ul class="">
<li>
<span>
The following composite values are also allowed:
</span>
<div class="dlist"><dl class="">
<dt class="hdlist1">
<em>none</em>
</dt>
<dd>
<p>
        No substitutions.
</p>
</dd>
<dt class="hdlist1">
<em>normal</em>
</dt>
<dd>
<p>
        The following substitutions:
        <em>specialcharacters</em>,<em>quotes</em>,<em>attributes</em>,<em>specialwords</em>,
        <em>replacements</em>,<em>macros</em>.
</p>
</dd>
<dt class="hdlist1">
<em>verbatim</em>
</dt>
<dd>
<p>
        <em>specialcharacters</em> and <em>callouts</em> substitutions.
</p>
</dd>
</dl></div>
</li>
<li>
<span>
<em>normal</em> and <em>verbatim</em> substitutions can be redefined by with
    <tt>subsnormal</tt> and <tt>subsverbatim</tt> entries in a configuration file
    <tt>[miscellaneous]</tt> section.
</span>
</li>
<li>
<span>
The substitutions are processed in the order in which they are
    listed and can appear more than once.
</span>
</li>
</ul>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
filter
</dt>
<dd>
<p>
  This optional entry specifies an executable shell command for
  processing block content (Paragraphs, DelimitedBlocks and Tables).
  The filter command can contain attribute references.
</p>
</dd>
<dt class="hdlist1">
posattrs
</dt>
<dd>
<p>
  Optional comma separated list of positional attribute names. This
  list maps positional attributes (in the block&#8217;s <a href="#X21">attribute   list</a>) to named block attributes. The following example, from the
  QuoteBlock definition, maps the first and section positional
  attributes:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>posattrs=attribution,citetitle</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
style
</dt>
<dd>
<p>
  This optional parameter specifies the default style name.
</p>
</dd>
<dt class="hdlist1">
&lt;stylename&gt;-style
</dt>
<dd>
<p>
  Optional style definition (see <a href="#X23">Styles</a> below).
</p>
</dd>
</dl></div>
<div class="paragraph">
<p>The following block parameters behave like document attributes and can
be set in block attribute lists and style definitions: <em>template</em>,
<em>options</em>, <em>subs</em>, <em>presubs</em>, <em>postsubs</em>, <em>filter</em>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X23">32.1. Styles</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="32.1. Styles";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>A style is a set of block attributes bundled as a single named
attribute. The following example defines a style named <em>verbatim</em>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>verbatim-style=template="literalblock",subs="verbatim"</tt></pre>
</div></div>
<ul class="">
<li>
<span>
All style parameter names must be suffixed with <tt>-style</tt> and the
  style parameter value is in the form of a list of <a href="#X21">named   attributes</a>.
</span>
</li>
<li>
<span>
Multi-item style attributes (<em>subs</em>,<em>presubs</em>,<em>postsubs</em>,<em>posattrs</em>)
  must be specified using Python tuple syntax rather than a simple
  list of values as they in separate entries e.g.
  <tt>postsubs=("callouts",)</tt> not <tt>postsubs="callouts"</tt>.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_paragraphs_2">32.2. Paragraphs</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="32.2. Paragraphs";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Paragraph translation is controlled by <tt>[paradef-*]</tt> configuration
file section entries. Users can define new types of paragraphs and
modify the behavior of existing types by editing AsciiDoc
configuration files.</p>
</div>
<div class="paragraph">
<p>Here is the shipped Default paragraph definition:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>[paradef-default]
delimiter=(?P&lt;text&gt;\S.*)
template=paragraph</tt></pre>
</div></div>
<div class="paragraph">
<p>The normal paragraph definition has a couple of special properties:</p>
</div>
<ol class="arabic">
<li>
<span>
It must exist and be defined in a configuration file section named
   <tt>[paradef-default]</tt>.
</span>
</li>
<li>
<span>
Irrespective of its position in the configuration files default
   paragraph document matches are attempted only after trying all
   other paragraph types.
</span>
</li>
</ol>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Paragraph specific block parameter notes:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
delimiter
</dt>
<dd>
<p>
  This regular expression must contain the named group <em>text</em> which
  matches the text on the first line.  Paragraphs are terminated by a
  blank line, the end of file, or the start of a DelimitedBlock.
</p>
</dd>
<dt class="hdlist1">
options
</dt>
<dd>
<p>
  The <em>listelement</em> option specifies that paragraphs of this type will
  automatically be considered part of immediately preceding list
  items.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="title">Paragraph processing proceeds as follows:</div><ol class="arabic">
<li>
<span>
The paragraph text is aligned to the left margin.
</span>
</li>
<li>
<span>
Optional <em>presubs</em> inline substitutions are performed on the
   paragraph text.
</span>
</li>
<li>
<span>
If a filter command is specified it is executed and the paragraph
   text piped to its standard input; the filter output replaces the
   paragraph text.
</span>
</li>
<li>
<span>
Optional <em>postsubs</em> inline substitutions are performed on the
   paragraph text.
</span>
</li>
<li>
<span>
The paragraph text is enveloped by the paragraph&#8217;s markup template
   and written to the output file.
</span>
</li>
</ol>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_delimited_blocks_2">32.3. Delimited Blocks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="32.3. Delimited Blocks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>DelimitedBlock <em>options</em> values are:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
sectionbody
</dt>
<dd>
<p>
    The block contents are processed as a SectionBody.
</p>
</dd>
<dt class="hdlist1">
skip
</dt>
<dd>
<p>
    The block is treated as a comment (see <a href="#X26">CommentBlocks</a>).
</p>
</dd>
</dl></div>
<div class="paragraph">
<p><em>presubs</em>, <em>postsubs</em> and <em>filter</em> entries are ignored when
<em>sectionbody</em> or <em>skip</em> options are set.</p>
</div>
<div class="paragraph">
<p>DelimitedBlock processing proceeds as follows:</p>
</div>
<ol class="arabic">
<li>
<span>
Optional <em>presubs</em> substitutions are performed on the block
   contents.
</span>
</li>
<li>
<span>
If a filter is specified it is executed and the block&#8217;s contents
   piped to its standard input. The filter output replaces the block
   contents.
</span>
</li>
<li>
<span>
Optional <em>postsubs</em> substitutions are performed on the block
   contents.
</span>
</li>
<li>
<span>
The block contents is enveloped by the block&#8217;s markup template and
   written to the output file.
</span>
</li>
</ol>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/tip.png" alt="Tip" />
</td>
<td class="content">Attribute expansion is performed on the block filter command
before it is executed, this is useful for passing arguments to the
filter.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_lists">32.4. Lists</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="32.4. Lists";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>List behavior and syntax is determined by <tt>[listdef-*]</tt> configuration
file sections. The user can change existing list behavior and add new
list types by editing configuration files.</p>
</div>
<div class="paragraph">
<p>List specific block definition notes:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
type
</dt>
<dd>
<p>
  This is either <em>bulleted</em>,<em>numbered</em>,<em>labeled</em> or <em>callout</em>.
</p>
</dd>
<dt class="hdlist1">
delimiter
</dt>
<dd>
<p>
  A Python regular expression that matches the first line of a
  list element entry. This expression can contain the named groups
  <em>text</em> (bulleted groups), <em>index</em> and <em>text</em> (numbered lists),
  <em>label</em> and <em>text</em> (labeled lists).
</p>
</dd>
<dt class="hdlist1">
tags
</dt>
<dd>
<p>
  The <tt>&lt;name&gt;</tt> of the <tt>[listtags-&lt;name&gt;]</tt> configuration file section
  containing list markup tag definitions.  The tag entries (<em>list</em>,
  <em>entry</em>, <em>label</em>, <em>term</em>, <em>text</em>) map the AsciiDoc list structure to
  backend markup; see the <em>listtags</em> sections in the AsciiDoc
  distributed backend <tt>.conf</tt> configuration files for examples.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_tables_2">32.5. Tables</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="32.5. Tables";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Table behavior and syntax is determined by <tt>[tabledef-*]</tt> and
<tt>[tabletags-*]</tt> configuration file sections. The user can change
existing table behavior and add new table types by editing
configuration files.  The following <tt>[tabledef-*]</tt> section entries
generate table output markup elements:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
colspec
</dt>
<dd>
<p>
  The table <em>colspec</em> tag definition.
</p>
</dd>
<dt class="hdlist1">
headrow, footrow, bodyrow
</dt>
<dd>
<p>
  Table header, footer and body row tag definitions. <em>headrow</em> and
  <em>footrow</em> table definition entries default to <em>bodyrow</em> if
  they are undefined.
</p>
</dd>
<dt class="hdlist1">
headdata, footdata, bodydata
</dt>
<dd>
<p>
  Table header, footer and body data tag definitions. <em>headdata</em> and
  <em>footdata</em> table definition entries default to <em>bodydata</em> if they
  are undefined.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
paragraph
</dt>
<dd>
<p>
  If the <em>paragraph</em> tag is specified then blank lines in the cell
  data are treated as paragraph delimiters and marked up using this
  tag.
</p>
</dd>
</dl></div>
<div class="paragraph" id="X4">
<p>Table behavior is also influenced by the following <tt>[miscellaneous]</tt>
configuration file entries:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
pagewidth
</dt>
<dd>
<p>
  This integer value is the printable width of the output media. See
  <a href="#X69">table attributes</a>.
</p>
</dd>
<dt class="hdlist1">
pageunits
</dt>
<dd>
<p>
  The units of width in output markup width attribute values.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="title">Table definition behavior</div><ul class="">
<li>
<span>
The output markup generation is specifically designed to work with
  the HTML and CALS (DocBook) table models, but should be adaptable to
  most XML table schema.
</span>
</li>
<li>
<span>
Table definitions can be &#8220;mixed in&#8221; from multiple cascading
  configuration files.
</span>
</li>
<li>
<span>
New table definitions inherit the default table and table tags
  definitions (<tt>[tabledef-default]</tt> and <tt>[tabletags-default]</tt>) so you
  only need to override those conf file entries that require
  modification.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X59">33. Filters</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="33. Filters";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc filters allow external commands to process AsciiDoc
<em>Paragraphs</em>, <em>DelimitedBlocks</em> and <em>Table</em> content. Filters are
primarily an extension mechanism for generating specialized outputs.
Filters are implemented using external commands which are specified in
configuration file definitions.</p>
</div>
<div class="paragraph">
<p>There&#8217;s nothing special about the filters, they&#8217;re just standard UNIX
filters: they read text from the standard input, process it, and write
to the standard output.</p>
</div>
<div class="paragraph">
<p>The <tt>asciidoc(1)</tt> command <tt>--filter</tt> option can be used to install and
remove filters.</p>
</div>
<div class="paragraph">
<p>Attribute substitution is performed on the filter command prior to
execution&#8201;&#8212;&#8201;attributes can be used to pass parameters from the
AsciiDoc source document to the filter.</p>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/warning.png" alt="Warning" />
</td>
<td class="content">Filters sometimes included executable code. Before installing
a filter you should verify that it is from a trusted source.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_filter_search_paths">33.1. Filter Search Paths</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="33.1. Filter Search Paths";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>If the filter command does not specify a directory path then
<tt>asciidoc(1)</tt> recursively searches for the executable filter command:</p>
</div>
<ul class="">
<li>
<span>
First it looks in the user&#8217;s <tt>$HOME/.asciidoc/filters</tt> directory.
</span>
</li>
<li>
<span>
Next the global filters directory (usually <tt>/etc/asciidoc/filters</tt>
  or <tt>/usr/local/etc/asciidoc</tt>) directory is searched.
</span>
</li>
<li>
<span>
Then it looks in the <tt>asciidoc(1)</tt> <tt>./filters</tt> directory.
</span>
</li>
<li>
<span>
Finally it relies on the executing shell to search the environment
  search path (<tt>$PATH</tt>).
</span>
</li>
</ul>
<div class="paragraph">
<p>Standard practice is to install each filter in it&#8217;s own sub-directory
with the same name as the filter&#8217;s style definition. For example the
music filter&#8217;s style name is <em>music</em> so it&#8217;s configuration and filter
files are stored in the <tt>filters/music</tt> directory.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_filter_configuration_files">33.2. Filter Configuration Files</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="33.2. Filter Configuration Files";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Filters are normally accompanied by a configuration file containing a
Paragraph or DelimitedBlock definition along with corresponding markup
templates.</p>
</div>
<div class="paragraph">
<p>While it is possible to create new <em>Paragraph</em> or <em>DelimitedBlock</em>
definitions the preferred way to implement a filter is to add a
<a href="#X23">style</a> to the existing Paragraph and ListingBlock definitions
(all filters shipped with AsciiDoc use this technique). The filter is
applied to the paragraph or delimited block by preceding it with an
attribute list: the first positional attribute is the style name,
remaining attributes are normally filter specific parameters.</p>
</div>
<div class="paragraph">
<p><tt>asciidoc(1)</tt> auto-loads all <tt>.conf</tt> files found in the filter search
paths (see previous section).</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X56">33.3. Example Filter</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="33.3. Example Filter";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc comes with a toy filter for highlighting source code keywords
and comments.  See also the <tt>./filters/code/code-filter-readme.txt</tt>
file.</p>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">The purpose of this toy filter is to demonstrate how to write a
filter&#8201;&#8212;&#8201;it&#8217;s much to simplistic to be passed off as a code syntax
highlighter.  If you want a full featured multi-language highlighter
use the <a href="http://www.methods.co.nz/asciidoc/source-highlight-filter.html">source code highlighter
filter</a>.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="listingblock">
<div class="content">
<pre><tt>.Code filter example
[code,python]
----------------------------------------------
''' A multi-line
    comment.'''
def sub_word(mo):
    ''' Single line comment.'''
    word = mo.group('word')   # Inline comment
    if word in keywords[language]:
        return quote + word + quote
    else:
        return word
----------------------------------------------</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Outputs:</p>
</div>
<div class="listingblock">
<div class="title">Code filter example</div>
<div class="content">
<pre><tt><i>''' A multi-line</i>
<i>    comment.'''</i>
<strong>def</strong> sub_word(mo):
<i>    ''' Single line comment.'''</i>
    word = mo.group('word')   <i># Inline comment</i>
    <strong>if</strong> word <strong>in</strong> keywords[language]:
        <strong>return</strong> quote + word + quote
    <strong>else</strong>:
        <strong>return</strong> word</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_built_in_filters">33.4. Built-in filters</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="33.4. Built-in filters";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The AsciiDoc distribution includes <em>source</em>, <em>music</em>, <em>latex</em> and
<em>graphviz</em> filters, details are on the
<a href="http://www.methods.co.nz/asciidoc/index.html#_filters">AsciiDoc website</a>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="X58">33.5. Filter plugins</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="33.5. Filter plugins";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Filter plugins are a simple mechanism for distributing AsciiDoc
filters.  A filter plugin is a Zip file containing the files that
constitute a filter. The <tt>asciidoc(1)</tt> <tt>--filter</tt> option implements
commands to install, remove and list filter plugins.  Filter plugin
commands and conventions are documented in the <tt>asciidoc(1)</tt> man page.
You can find a list of filter plugins on the
<a href="http://www.methods.co.nz/asciidoc/filters.html">AsciiDoc website</a>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X36">34. Help Commands</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="34. Help Commands";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <tt>asciidoc(1)</tt> command has a <tt>--help</tt> option which prints help topics
to stdout. The default topic summarizes <tt>asciidoc(1)</tt> usage:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc --help</tt></pre>
</div></div>
<div class="paragraph">
<p>To print a list of help topics:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc --help=topics</tt></pre>
</div></div>
<div class="paragraph">
<p>To print a help topic specify the topic name as a command argument.
Help topic names can be shortened so long as they are not ambiguous.
Examples:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc --help=manpage
$ asciidoc -hm              # Short version of previous example.
$ asciidoc --help=syntax
$ asciidoc -hs              # Short version of previous example.</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_customizing_help">34.1. Customizing Help</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="34.1. Customizing Help";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>To change, delete or add your own help topics edit a help
configuration file.  The help file name <tt>help-&lt;lang&gt;.conf</tt> is based on
the setting of the <tt>lang</tt> attribute, it defaults to <tt>help.conf</tt>
(English).  The <a href="#X27">help file location</a> will depend on whether you
want the topics to apply to all users or just the current user.</p>
</div>
<div class="paragraph">
<p>The help topic files have the same named section format as other
<a href="#X7">configuration files</a>. The <tt>help.conf</tt> files are stored in the
same locations and loaded in the same order as other configuration
files.</p>
</div>
<div class="paragraph">
<p>When the <tt>--help</tt> command-line option is specified AsciiDoc loads the
appropriate help files and then prints the contents of the section
whose name matches the help topic name.  If a topic name is not
specified <tt>default</tt> is used. You don&#8217;t need to specify the whole help
topic name on the command-line, just enough letters to ensure it&#8217;s not
ambiguous. If a matching help file section is not found a list of
available topics is printed.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_tips_and_tricks">35. Tips and Tricks</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="35. Tips and Tricks";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="_know_your_editor">35.1. Know Your Editor</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.1. Know Your Editor";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Writing AsciiDoc documents will be a whole lot more pleasant if you
know your favorite text editor. Learn how to indent and reformat text
blocks, paragraphs, lists and sentences. <a href="#X20">Tips for <em>vim</em> users</a>
follow.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X20">35.2. Vim Commands for Formatting AsciiDoc</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.2. Vim Commands for Formatting AsciiDoc";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect3">
<h1 id="_text_wrap_paragraphs">35.2.1. Text Wrap Paragraphs</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="35.2.1. Text Wrap Paragraphs";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Use the vim <tt>:gq</tt> command to reformat paragraphs. Setting the
<em>textwidth</em> sets the right text wrap margin; for example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>:set textwidth=70</tt></pre>
</div></div>
<div class="paragraph">
<p>To reformat a paragraph:</p>
</div>
<ol class="arabic">
<li>
<span>
Position the cursor at the start of the paragraph.
</span>
</li>
<li>
<span>
Type <tt>gq}</tt>.
</span>
</li>
</ol>
<div class="paragraph">
<p>Execute <tt>:help gq</tt> command to read about the vim gq command.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/tip.png" alt="Tip" />
</td>
<td class="content">
<ul class="">
<li>
<span>
Assign the <tt>gq}</tt> command to the Q key with the <tt>nnoremap Q gq}</tt>
  command or put it in your <tt>~/.vimrc</tt> file to so it&#8217;s always
  available (see the <a href="#X61">Example <tt>~/.vimrc</tt> file</a>).
</span>
</li>
<li>
<span>
Put <tt>set</tt> commands in your <tt>~/.vimrc</tt> file so you don&#8217;t have to
  enter them manually.
</span>
</li>
<li>
<span>
The Vim website (<a href="http://www.vim.org">http://www.vim.org</a>) has a wealth of resources,
  including scripts for automated spell checking and ASCII Art
  drawing.
</span>
</li>
</ul>
</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="_format_lists">35.2.2. Format Lists</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="35.2.2. Format Lists";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <tt>gq</tt> command can also be used to format bulleted, numbered and
callout lists. First you need to set the <tt>comments</tt>, <tt>formatoptions</tt>
and <tt>formatlistpat</tt> (see the <a href="#X61">Example <tt>~/.vimrc</tt> file</a>).</p>
</div>
<div class="paragraph">
<p>Now you can format simple lists that use dash, asterisk, period and
plus bullets along with numbered ordered lists:</p>
</div>
<ol class="arabic">
<li>
<span>
Position the cursor at the start of the list.
</span>
</li>
<li>
<span>
Type <tt>gq}</tt>.
</span>
</li>
</ol>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect3">
<h1 id="_indent_paragraphs">35.2.3. Indent Paragraphs</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="35.2.3. Indent Paragraphs";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Indent whole paragraphs by indenting the fist line with the desired
indent and then executing the <tt>gq}</tt> command.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect3">
<h1 id="X61">35.2.4. Example <tt>~/.vimrc</tt> File</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect3";nexttitle="35.2.4. Example <tt>~/.vimrc</tt> File";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="listingblock">
<div class="content">
<pre><tt>" Use bold bright fonts.
set background=dark

" Show tabs and trailing characters.
set listchars=tab:»·,trail:·
set list

" Don't highlight searched text.
highlight clear Search

" Don't move to matched text while search pattern is being entered.
set noincsearch

" Reformat paragraphs and list.
nnoremap R gq}

" Delete trailing white space and Dos-returns and to expand tabs to spaces.
nnoremap S :set et&lt;CR&gt;:retab!&lt;CR&gt;:%s/[\r \t]\+$//&lt;CR&gt;

autocmd BufRead,BufNewFile *.txt,README,TODO,CHANGELOG,NOTES
        \ setlocal autoindent expandtab tabstop=8 softtabstop=2 shiftwidth=2 filetype=asciidoc
        \ textwidth=70 wrap formatoptions=tcqn
        \ formatlistpat=^\\s*\\d\\+\\.\\s\\+\\\\|^\\s*&lt;\\d\\+&gt;\\s\\+\\\\|^\\s*[a-zA-Z.]\\.\\s\\+\\\\|^\\s*[ivxIVX]\\+\\.\\s\\+
        \ comments=s1:/*,ex:*/,://,b:#,:%,:XCOMM,fb:-,fb:*,fb:+,fb:.,fb:&gt;</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_troubleshooting">35.3. Troubleshooting</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.3. Troubleshooting";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc diagnostic features are detailed in the <a href="#X82">Diagnostics appendix</a>.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_gotchas">35.4. Gotchas</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.4. Gotchas";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="dlist"><dl class="">
<dt class="hdlist1">
Incorrect character encoding
</dt>
<dd>
<p>
    If you get an error message like <tt>'UTF-8' codec can't decode ...</tt>
    then you source file contains invalid UTF-8 characters&#8201;&#8212;&#8201;set the
    AsciiDoc <a href="#X54">encoding attribute</a> for the correct character set
    (typically ISO-8859-1 (Latin-1) for European languages).
</p>
</dd>
<dt class="hdlist1">
Invalid output
</dt>
<dd>
<p>
    AsciiDoc attempts to validate the input AsciiDoc source but makes
    no attempt to validate the output markup, it leaves that to
    external tools such as <tt>xmllint(1)</tt> (integrated into <tt>a2x(1)</tt>).
    Backend validation cannot be hardcoded into AsciiDoc because
    backends are dynamically configured. The following example
    generates valid HTML but invalid DocBook (the DocBook <tt>literal</tt>
    element cannot contain an <tt>emphasis</tt> element):
</p>
<div class="literalblock">
<div class="content">
<pre><tt>+monospaced text with an _emphasized_ word+</tt></pre>
</div></div>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
Misinterpreted text formatting
</dt>
<dd>
<p>
    You can suppress markup expansion by placing a backslash character
    immediately in front of the element. The following example
    suppresses inline monospaced formatting:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>\+1 for C++.</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
Overlapping text formatting
</dt>
<dd>
<p>
    Overlapping text formatting will generate illegal overlapping
    markup tags which will result in downstream XML parsing errors.
    Here&#8217;s an example:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>Some *strong markup _that overlaps* emphasized markup_.</tt></pre>
</div></div>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
Ambiguous underlines
</dt>
<dd>
<p>
    A DelimitedBlock can immediately follow a paragraph without an
    intervening blank line, but be careful, a single line paragraph
    underline may be misinterpreted as a section title underline
    resulting in a &#8220;closing block delimiter expected&#8221; error.
</p>
</dd>
<dt class="hdlist1">
Ambiguous ordered list items
</dt>
<dd>
<p>
    Lines beginning with numbers at the end of sentences will be
    interpreted as ordered list items.  The following example
    (incorrectly) begins a new list with item number 1999:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>He was last sighted in
1999. Since then things have moved on.</tt></pre>
</div></div>
<div class="paragraph">
<p>The <em>list item out of sequence</em> warning makes it unlikely that this
problem will go unnoticed.</p>
</div>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="dlist"><dl class="">
<dt class="hdlist1">
Special characters in attribute values
</dt>
<dd>
<p>
    Special character substitution precedes attribute substitution so
    if attribute values contain special characters you may, depending
    on the substitution context, need to escape the special characters
    yourself. For example:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -a 'orgname=Bill &amp;amp; Ben Inc.' mydoc.txt</tt></pre>
</div></div>
</dd>
<dt class="hdlist1">
Attribute lists
</dt>
<dd>
<p>
    If any named attribute entries are present then all string
    attribute values must be quoted.  For example:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>["Desktop screenshot",width=32]</tt></pre>
</div></div>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="X90">35.5. Combining separate documents</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.5. Combining separate documents";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>You have a number of stand-alone AsciiDoc documents that you want to
process as a single document. Simply processing them with a series of
<tt>include</tt> macros won&#8217;t work because the documents contain (level 0)
document titles.  The solution is to create a top level wrapper
document and use the <tt>leveloffset</tt> attribute to push them all down one
level. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>Combined Document Title
=======================

// Push titles down one level.
:leveloffset: 1

include::document1.txt[]

// Return to normal title levels.
:leveloffset: 0

A Top Level Section
-------------------
Lorum ipsum.

// Push titles down one level.
:leveloffset: 1

include::document2.txt[]

include::document3.txt[]</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>The document titles in the included documents will now be processed as
level 1 section titles, level 1 sections as level 2 sections and so
on.</p>
</div>
<ul class="">
<li>
<span>
Put a blank line between the <tt>include</tt> macro lines to ensure the
  title of the included document is not seen as part of the last
  paragraph of the previous document.
</span>
</li>
<li>
<span>
You won&#8217;t want non-title document header lines (for example, Author
  and Revision lines) in the included files&#8201;&#8212;&#8201;conditionally exclude
  them if they are necessary for stand-alone processing.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_processing_document_sections_separately">35.6. Processing document sections separately</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.6. Processing document sections separately";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>You have divided your AsciiDoc document into separate files (one per
top level section) which are combined and processed with the following
top level document:</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>Combined Document Title
=======================
Joe Bloggs
v1.0, 12-Aug-03

include::section1.txt[]

include::section2.txt[]

include::section3.txt[]</tt></pre>
</div></div>
<div class="paragraph">
<p>You also want to process the section files as separate documents.
This is easy because <tt>asciidoc(1)</tt> will quite happily process
<tt>section1.txt</tt>, <tt>section2.txt</tt> and <tt>section3.txt</tt> separately&#8201;&#8212;&#8201;the
resulting output documents contain the section but have no document
title.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_processing_document_snippets">35.7. Processing document snippets</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.7. Processing document snippets";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Use the <tt>-s</tt> (<tt>--no-header-footer</tt>) command-line option to suppress
header and footer output, this is useful if the processed output is to
be included in another file. For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -sb docbook section1.txt</tt></pre>
</div></div>
<div class="paragraph">
<p><tt>asciidoc(1)</tt> can be used as a filter, so you can pipe chunks of text
through it. For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ echo 'Hello *World!*' | asciidoc -s -
&lt;div class="paragraph"&gt;&lt;p&gt;Hello &lt;strong&gt;World!&lt;/strong&gt;&lt;/p&gt;&lt;/div&gt;</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="_badges_in_html_page_footers">35.8. Badges in HTML page footers</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.8. Badges in HTML page footers";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>See the <tt>[footer]</tt> section in the AsciiDoc distribution <tt>xhtml11.conf</tt>
configuration file.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_pretty_printing_asciidoc_output">35.9. Pretty printing AsciiDoc output</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.9. Pretty printing AsciiDoc output";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>If the indentation and layout of the <tt>asciidoc(1)</tt> output is not to your
liking you can:</p>
</div>
<ol class="arabic">
<li>
<span>
Change the indentation and layout of configuration file markup
   template sections. The <tt>{empty}</tt> attribute is useful for outputting
   trailing blank lines in markup templates.
</span>
</li>
<li>
<span>
Use Dave Raggett&#8217;s <a href="http://tidy.sourceforge.net/">HTML Tidy</a> program
   to tidy <tt>asciidoc(1)</tt> output. Example:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -b docbook -o - mydoc.txt | tidy -indent -xml &gt;mydoc.xml</tt></pre>
</div></div>
</li>
<li>
<span>
Use the <tt>xmllint(1)</tt> format option. Example:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>$ xmllint --format mydoc.xml</tt></pre>
</div></div>
</li>
</ol>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_supporting_minor_docbook_dtd_variations">35.10. Supporting minor DocBook DTD variations</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.10. Supporting minor DocBook DTD variations";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The conditional inclusion of DocBook SGML markup at the end of the
distribution <tt>docbook45.conf</tt> file illustrates how to support minor
DTD variations. The included sections override corresponding entries
from preceding sections.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="_creating_stand_alone_html_documents">35.11. Creating stand-alone HTML documents</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.11. Creating stand-alone HTML documents";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>If you&#8217;ve ever tried to send someone an HTML document that includes
stylesheets and images you&#8217;ll know that it&#8217;s not as straight-forward
as exchanging a single file.  AsciiDoc has options to create
stand-alone documents containing embedded images, stylesheets and
scripts.  The following AsciiDoc command creates a single file
containing <a href="#X66">embedded images</a>, CSS stylesheets, and JavaScript
(for table of contents and footnotes):</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt</tt></pre>
</div></div>
<div class="paragraph">
<p>You can view the HTML file here: <a href="http://www.methods.co.nz/asciidoc/article-standalone.html">http://www.methods.co.nz/asciidoc/article-standalone.html</a></p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_shipping_stand_alone_asciidoc_source">35.12. Shipping stand-alone AsciiDoc source</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.12. Shipping stand-alone AsciiDoc source";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Reproducing presentation documents from someone else&#8217;s source has one
major problem: unless your configuration files are the same as the
creator&#8217;s you won&#8217;t get the same output.</p>
</div>
<div class="paragraph">
<p>The solution is to create a single backend specific configuration file
using the <tt>asciidoc(1)</tt> <tt>-c</tt> (<tt>--dump-conf</tt>) command-line option. You
then ship this file along with the AsciiDoc source document plus the
<tt>asciidoc.py</tt> script. The only end user requirement is that they have
Python installed (and that they consider you a trusted source). This
example creates a composite HTML configuration file for <tt>mydoc.txt</tt>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -cb xhtml11 mydoc.txt &gt; mydoc-xhtml11.conf</tt></pre>
</div></div>
<div class="paragraph">
<p>Ship <tt>mydoc.txt</tt>, <tt>mydoc-html.conf</tt>, and <tt>asciidoc.py</tt>. With
these three files (and a Python interpreter) the recipient can
regenerate the HMTL output:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ ./asciidoc.py -eb xhtml11 mydoc.txt</tt></pre>
</div></div>
<div class="paragraph">
<p>The <tt>-e</tt> (<tt>--no-conf</tt>) option excludes the use of implicit
configuration files, ensuring that only entries from the
<tt>mydoc-html.conf</tt> configuration are used.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_inserting_blank_space">35.13. Inserting blank space</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.13. Inserting blank space";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Adjust your style sheets to add the correct separation between block
elements. Inserting blank paragraphs containing a single non-breaking
space character <tt>{nbsp}</tt> works but is an ad hoc solution compared
to using style sheets.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_closing_open_sections">35.14. Closing open sections</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.14. Closing open sections";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>You can close off section tags up to level <tt>N</tt> by calling the
<tt>eval::[Section.setlevel(N)]</tt> system macro. This is useful if you
want to include a section composed of raw markup. The following
example includes a DocBook glossary division at the top section level
(level 0):</p>
</div>
<div class="listingblock">
<div class="content">
<pre><tt>ifdef::basebackend-docbook[]

eval::[Section.setlevel(0)]

+++++++++++++++++++++++++++++++
&lt;glossary&gt;
  &lt;title&gt;Glossary&lt;/title&gt;
  &lt;glossdiv&gt;
  ...
  &lt;/glossdiv&gt;
&lt;/glossary&gt;
+++++++++++++++++++++++++++++++
endif::basebackend-docbook[]</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_validating_output_files">35.15. Validating output files</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="35.15. Validating output files";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Use <tt>xmllint(1)</tt> to check the AsciiDoc generated markup is both well
formed and valid. Here are some examples:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ xmllint --nonet --noout --valid docbook-file.xml
$ xmllint --nonet --noout --valid xhtml11-file.html
$ xmllint --nonet --noout --valid --html html4-file.html</tt></pre>
</div></div>
<div class="paragraph">
<p>The <tt>--valid</tt> option checks the file is valid against the document
type&#8217;s DTD, if the DTD is not installed in your system&#8217;s catalog then
it will be fetched from its Internet location. If you omit the
<tt>--valid</tt> option the document will only be checked that it is well
formed.</p>
</div>
<div class="paragraph">
<p>The online <a href="http://validator.w3.org/#validate_by_uri+with_options">W3C
Markup Validation Service</a> is the defacto standard when it comes to
validating HTML (it validates all HTML standards including HTML5).</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_glossary">Glossary</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="Glossary";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="dlist glossary"><dl>
<dt>
<a id="X8"></a> Block element
</dt>
<dd>
<p>
    An AsciiDoc block element is a document entity composed of one or
    more whole lines of text.
</p>
</dd>
<dt>
<a id="X34"></a> Inline element
</dt>
<dd>
<p>
    AsciiDoc inline elements occur within block element textual
    content, they perform formatting and substitution tasks.
</p>
</dd>
<dt>
Formal element
</dt>
<dd>
<p>
    An AsciiDoc block element that has a BlockTitle. Formal elements
    are normally listed in front or back matter, for example lists of
    tables, examples and figures.
</p>
</dd>
<dt>
Verbatim element
</dt>
<dd>
<p>
    The word verbatim indicates that white space and line breaks in
    the source document are to be preserved in the output document.
</p>
</dd>
</dl></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_migration_notes">Appendix A: Migration Notes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="Migration Notes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>

<div class="sect2">
<h1 id="X53">» Version 7 to version 8</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="» Version 7 to version 8";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<ul class="">
<li>
<span>
A new set of quotes has been introduced which may match inline text
  in existing documents&#8201;&#8212;&#8201;if they do you&#8217;ll need to escape the
  matched text with backslashes.
</span>
</li>
<li>
<span>
The index entry inline macro syntax has changed&#8201;&#8212;&#8201;if your documents
  include indexes you may need to edit them.
</span>
</li>
<li>
<span>
Replaced <tt>a2x(1)</tt> <tt>--no-icons</tt> and <tt>--no-copy</tt> options with their
  negated equivalents: <tt>--icons</tt> and <tt>--copy</tt> respectively. The
  default behavior has also changed&#8201;&#8212;&#8201;the use of icons and copying of
  icon and CSS files must be specified explicitly with the <tt>--icons</tt>
  and <tt>--copy</tt> options.
</span>
</li>
</ul>
<div class="paragraph">
<p>The rationale for the changes can be found in the AsciiDoc
<tt>CHANGELOG</tt>.</p>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">If you want to disable unconstrained quotes, the new alternative
constrained quotes syntax and the new index entry syntax then you can
define the attribute <tt>asciidoc7compatible</tt> (for example by using the
<tt>-a asciidoc7compatible</tt> command-line option).</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X38">Appendix B: Packager Notes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="Packager Notes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Read the <tt>README</tt> and <tt>INSTALL</tt> files (in the distribution root
directory) for install prerequisites and procedures.  The distribution
<tt>Makefile.in</tt> (used by <tt>configure</tt> to generate the <tt>Makefile</tt>) is the
canonical installation procedure.</p>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X39">Appendix C: AsciiDoc Safe Mode</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="AsciiDoc Safe Mode";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc <em>safe mode</em> skips potentially dangerous scripted sections in
AsciiDoc source files by inhibiting the execution of arbitrary code or
the inclusion of arbitrary files.</p>
</div>
<div class="paragraph">
<p>The safe mode is disabled by default, it can be enabled with the
<tt>asciidoc(1)</tt> <tt>--safe</tt> command-line option.</p>
</div>
<div class="title">Safe mode constraints</div><ul class="">
<li>
<span>
<tt>eval</tt>, <tt>sys</tt> and <tt>sys2</tt> executable attributes and block macros are
  not executed.
</span>
</li>
<li>
<span>
<tt>include::&lt;filename&gt;[]</tt> and <tt>include1::&lt;filename&gt;[]</tt> block macro
  files must reside inside the parent file&#8217;s directory.
</span>
</li>
<li>
<span>
<tt>{include:&lt;filename&gt;}</tt> executable attribute files must reside
  inside the source document directory.
</span>
</li>
<li>
<span>
Passthrough Blocks are dropped.
</span>
</li>
</ul>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/warning.png" alt="Warning" />
</td>
<td class="content">
<div class="paragraph">
<p>The safe mode is not designed to protect against unsafe AsciiDoc
configuration files. Be especially careful when:</p>
</div>
<ol class="arabic">
<li>
<span>
Implementing filters.
</span>
</li>
<li>
<span>
Implementing elements that don&#8217;t escape special characters.
</span>
</li>
<li>
<span>
Accepting configuration files from untrusted sources.
</span>
</li>
</ol>
</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_using_asciidoc_with_non_english_languages">Appendix D: Using AsciiDoc with non-English Languages</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="Using AsciiDoc with non-English Languages";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc can process UTF-8 character sets but there are some things
you need to be aware of:</p>
</div>
<ul class="">
<li>
<span>
If you are generating output documents using a DocBook toolchain
  then you should set the AsciiDoc <tt>lang</tt> attribute to the appropriate
  language (it defaults to <tt>en</tt> (English)). This will ensure things
  like table of contents, figure and table captions and admonition
  captions are output in the specified language.  For example:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>$ a2x -a lang=es doc/article.txt</tt></pre>
</div></div>
</li>
<li>
<span>
If you are outputting HTML directly from <tt>asciidoc(1)</tt> you&#8217;ll
  need to set the various <tt>*_caption</tt> attributes to match your target
  language (see the list of captions and titles in the <tt>[attributes]</tt>
  section of the distribution <tt>lang-*.conf</tt> files). The easiest way is
  to create a language <tt>.conf</tt> file (see the AsciiDoc&#8217;s <tt>lang-en.conf</tt>
  file).
</span>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">You still use the <em>NOTE</em>, <em>CAUTION</em>, <em>TIP</em>, <em>WARNING</em>,
<em>IMPORTANT</em> captions in the AsciiDoc source, they get translated in
the HTML output file.</td>
</tr></table>
</div>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<ul class="">
<li>
<span>
<tt>asciidoc(1)</tt> automatically loads configuration files named like
  <tt>lang-&lt;lang&gt;.conf</tt> where <tt>&lt;lang&gt;</tt> is a two letter language code that
  matches the current AsciiDoc <tt>lang</tt> attribute. See also
  <a href="#X27">Configuration File Names and Locations</a>.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_vim_syntax_highlighter">Appendix E: Vim Syntax Highlighter</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="Vim Syntax Highlighter";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Syntax highlighting is incredibly useful, in addition to making
reading AsciiDoc documents much easier syntax highlighting also helps
you catch AsciiDoc syntax errors as you write your documents.</p>
</div>
<div class="paragraph">
<p>The AsciiDoc <tt>./vim/</tt> distribution directory contains Vim syntax
highlighter and filetype detection scripts for AsciiDoc.  Syntax
highlighting makes it much easier to spot AsciiDoc syntax errors.</p>
</div>
<div class="paragraph">
<p>If Vim is installed on your system the AsciiDoc installer
(<tt>install.sh</tt>) will automatically install the vim scripts in the Vim
global configuration directory (<tt>/etc/vim</tt>).</p>
</div>
<div class="paragraph">
<p>You can also turn on syntax highlighting by adding the following line
to the end of you AsciiDoc source files:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>// vim: set syntax=asciidoc:</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/tip.png" alt="Tip" />
</td>
<td class="content">Bold fonts are often easier to read, use the Vim <tt>:set
background=dark</tt> command to set bold bright fonts.</td>
</tr></table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">There are a number of alternative syntax highlighters for
various editors listed on the <a href="http://www.methods.co.nz/asciidoc/">AsciiDoc website</a>.</td>
</tr></table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect2">
<h1 id="_limitations">» Limitations</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect2";nexttitle="» Limitations";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The current implementation does a reasonable job but on occasions gets
things wrong:</p>
</div>
<ul class="">
<li>
<span>
Nested quoted text formatting is highlighted according to the outer
  format.
</span>
</li>
<li>
<span>
If a closing Example Block delimiter is sometimes mistaken for a
  title underline. A workaround is to insert a blank line before the
  closing delimiter.
</span>
</li>
<li>
<span>
Lines within a paragraph starting with equals characters may be
  highlighted as single-line titles.
</span>
</li>
<li>
<span>
Lines within a paragraph beginning with a period may be highlighted
  as block titles.
</span>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X74">Appendix F: Attribute Options</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="Attribute Options";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>Here is the list of predefined <a href="#X75">attribute list options</a>:</p>
</div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="hsides"
cellspacing="0" cellpadding="4">
<col width="18%" />
<col width="18%" />
<col width="18%" />
<col width="45%" />
<thead>
<tr>
<th align="left" valign="top">Option</th>
<th align="left" valign="top">Backends</th>
<th align="left" valign="top">AsciiDoc Elements</th>
<th align="left" valign="top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><em>autowidth</em></p></td>
<td align="left" valign="top"><p class="table">xhtml11, html5, html4</p></td>
<td align="left" valign="top"><p class="table">table</p></td>
<td align="left" valign="top"><p class="table">The column widths are determined by the browser, not the AsciiDoc
<em>cols</em> attribute. If there is no <em>width</em> attribute the table width is
also left up to the browser.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>breakable, unbreakable</em></p></td>
<td align="left" valign="top"><p class="table">docbook (XSL/FO)</p></td>
<td align="left" valign="top"><p class="table">table, example, block image</p></td>
<td align="left" valign="top"><p class="table">The <em>breakable</em> options allows block elements to break across page
boundaries; <em>unbreakable</em> attempts to keep the block element together
on a single page. If neither option is specified the default XSL
stylesheet behavior prevails.</p></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
width="100%"
frame="hsides"
cellspacing="0" cellpadding="4">
<col width="18%" />
<col width="18%" />
<col width="18%" />
<col width="45%" />
<thead>
<tr>
<th align="left" valign="top">Option</th>
<th align="left" valign="top">Backends</th>
<th align="left" valign="top">AsciiDoc Elements</th>
<th align="left" valign="top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><em>compact</em></p></td>
<td align="left" valign="top"><p class="table">docbook, xhtml11</p></td>
<td align="left" valign="top"><p class="table">bulleted list, numbered list</p></td>
<td align="left" valign="top"><p class="table">Minimizes vertical space in the list</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>footer</em></p></td>
<td align="left" valign="top"><p class="table">docbook, xhtml11, html5, html4</p></td>
<td align="left" valign="top"><p class="table">table</p></td>
<td align="left" valign="top"><p class="table">The last row of the table is rendered as a footer.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>header</em></p></td>
<td align="left" valign="top"><p class="table">docbook, xhtml11, html5, html4</p></td>
<td align="left" valign="top"><p class="table">table</p></td>
<td align="left" valign="top"><p class="table">The first row of the table is rendered as a header.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>pgwide</em></p></td>
<td align="left" valign="top"><p class="table">docbook (XSL/FO)</p></td>
<td align="left" valign="top"><p class="table">table, block image, horizontal labeled list</p></td>
<td align="left" valign="top"><p class="table">Specifies that the element should be rendered across the full text
width of the page irrespective of the current indentation.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>strong</em></p></td>
<td align="left" valign="top"><p class="table">xhtml11, html5, html4</p></td>
<td align="left" valign="top"><p class="table">labeled lists</p></td>
<td align="left" valign="top"><p class="table">Emboldens label text.</p></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X82">Appendix G: Diagnostics</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="Diagnostics";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>The <tt>asciidoc(1)</tt> <tt>--verbose</tt> command-line option prints additional
information to stderr: files processed, filters processed, warnings,
system attribute evaluation.</p>
</div>
<div class="paragraph">
<p>A special attribute named <em>trace</em> enables the output of
element-by-element diagnostic messages detailing output markup
generation to stderr.  The <em>trace</em> attribute can be set on the
command-line or from within the document using <a href="#X18">Attribute Entries</a> (the latter allows tracing to be confined to specific
portions of the document).</p>
</div>
<ul class="">
<li>
<span>
Trace messages print the source file name and line number and the
  trace name followed by related markup.
</span>
</li>
<li>
<span>
<em>trace names</em> are normally the names of AsciiDoc elements (see the
  list below).
</span>
</li>
<li>
<span>
The trace message is only printed if the <em>trace</em> attribute value
  matches the start of a <em>trace name</em>. The <em>trace</em> attribute value can
  be any Python regular expression.  If a trace value is not specified
  all trace messages will be printed (this can result in large amounts
  of output if applied to the whole document).
</span>
</li>
<li>
<span>
In the case of inline substitutions:
</span>
<ul class="">
<li>
<span>
The text before and after the substitution is printed; the before
    text is preceded by a line containing <tt>&lt;&lt;&lt;</tt> and the after text by
    a line containing <tt>&gt;&gt;&gt;</tt>.
</span>
</li>
<li>
<span>
The <em>subs</em> trace value is an alias for all inline substitutions.
</span>
</li>
</ul>
</li>
</ul>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="literalblock">
<div class="title">Trace names</div>
<div class="content">
<pre><tt>&lt;blockname&gt; block close
&lt;blockname&gt; block open
&lt;subs&gt;
dropped line (a line containing an undefined attribute reference).
floating title
footer
header
list close
list entry close
list entry open
list item close
list item open
list label close
list label open
list open
macro block (a block macro)
name (man page NAME section)
paragraph
preamble close
preamble open
section close
section open: level &lt;level&gt;
subs (all inline substitutions)
table</tt></pre>
</div></div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Where:</p>
</div>
<ul class="">
<li>
<span>
<tt>&lt;level&gt;</tt> is section level number <em>0&#8230;4</em>.
</span>
</li>
<li>
<span>
<tt>&lt;blockname&gt;</tt> is a delimited block name: <em>comment</em>, <em>sidebar</em>,
  <em>open</em>, <em>pass</em>, <em>listing</em>, <em>literal</em>, <em>quote</em>, <em>example</em>.
</span>
</li>
<li>
<span>
<tt>&lt;subs&gt;</tt> is an inline substitution type:
  <em>specialcharacters</em>,<em>quotes</em>,<em>specialwords</em>, <em>replacements</em>,
  <em>attributes</em>,<em>macros</em>,<em>callouts</em>, <em>replacements2</em>.
</span>
</li>
</ul>
<div class="paragraph">
<p>Command-line examples:</p>
</div>
<ol class="arabic">
<li>
<span>
Trace the entire document.
</span>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -a trace mydoc.txt</tt></pre>
</div></div>
</li>
<li>
<span>
Trace messages whose names start with <tt>quotes</tt> or <tt>macros</tt>:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -a 'trace=quotes|macros'  mydoc.txt</tt></pre>
</div></div>
</li>
<li>
<span>
Print the first line of each trace message:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -a trace mydoc.txt 2&gt;&amp;1 | grep ^TRACE:</tt></pre>
</div></div>
</li>
</ol>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="paragraph">
<p>Attribute Entry examples:</p>
</div>
<ol class="arabic">
<li>
<span>
Begin printing all trace messages:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>:trace:</tt></pre>
</div></div>
</li>
<li>
<span>
Print only matched trace messages:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>:trace: quotes|macros</tt></pre>
</div></div>
</li>
<li>
<span>
Turn trace messages off:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>:trace!:</tt></pre>
</div></div>
</li>
</ol>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="X88">Appendix H: Backend Attributes</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="Backend Attributes";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>This table contains a list of optional attributes that influence the
generated outputs.</p>
</div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="hsides"
cellspacing="0" cellpadding="4">
<col width="14%" />
<col width="14%" />
<col width="71%" />
<thead>
<tr>
<th align="left" valign="top">Name </th>
<th align="left" valign="top">Backends </th>
<th align="left" valign="top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><em>badges</em></p></td>
<td align="left" valign="top"><p class="table">xhtml11, html5</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Link badges (<em>XHTML 1.1</em> and <em>CSS</em>) in document footers. By default
badges are omitted (<em>badges</em> is undefined).</p>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="../images/icons/note.png" alt="Note" />
</td>
<td class="content">The path names of images, icons and scripts are relative path
names to the output document not the source document.</td>
</tr></table>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>data-uri</em></p></td>
<td align="left" valign="top"><p class="table">xhtml11, html5</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Embed images using the <a href="#X66">data: uri scheme</a>.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>css-signature</em></p></td>
<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Set a <em>CSS signature</em> for the document (sets the <em>id</em> attribute of the
HTML <em>body</em> element). CSS signatures provide a mechanism that allows
users to personalize the document appearance. The term <em>CSS signature</em>
was <a href="http://archivist.incutio.com/viewlist/css-discuss/13291">coined by
Eric Meyer</a>.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>disable-javascript</em></p></td>
<td align="left" valign="top"><p class="table">xhtml11, html5</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>If the <tt>disable-javascript</tt> attribute is defined the <tt>asciidoc.js</tt>
JavaScript is not embedded or linked to the output document.  By
default AsciiDoc automatically embeds or links the <tt>asciidoc.js</tt>
JavaScript to the output document. The script dynamically generates
<a href="#X91">table of contents</a> and <a href="#X92">footnotes</a>.</p>
</div></div></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
width="100%"
frame="hsides"
cellspacing="0" cellpadding="4">
<col width="14%" />
<col width="14%" />
<col width="71%" />
<thead>
<tr>
<th align="left" valign="top">Name </th>
<th align="left" valign="top">Backends </th>
<th align="left" valign="top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><em><a id="X97"></a> docinfo, docinfo1, docinfo2</em></p></td>
<td align="left" valign="top"><p class="table">All backends</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>These three attributes control which <a href="#X87">document information files</a> will be included in the the header of the output file:</p>
</div>
<div class="dlist"><dl class="">
<dt class="hdlist1">
docinfo
</dt>
<dd>
<p>
Include <tt>&lt;filename&gt;-docinfo.&lt;ext&gt;</tt>
</p>
</dd>
<dt class="hdlist1">
docinfo1
</dt>
<dd>
<p>
Include <tt>docinfo.&lt;ext&gt;</tt>
</p>
</dd>
<dt class="hdlist1">
docinfo2
</dt>
<dd>
<p>
Include <tt>docinfo.&lt;ext&gt;</tt> and <tt>&lt;filename&gt;-docinfo.&lt;ext&gt;</tt>
</p>
</dd>
</dl></div>
<div class="paragraph">
<p>Where <tt>&lt;filename&gt;</tt> is the file name (sans extension) of the AsciiDoc
input file and <tt>&lt;ext&gt;</tt> is <tt>.html</tt> for HTML outputs or <tt>.xml</tt> for
DocBook outputs. If the input file is the standard input then the
output file name is used. The following example will include the
<tt>mydoc-docinfo.xml</tt> docinfo file in the DocBook <tt>mydoc.xml</tt> output
file:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -a docinfo -b docbook mydoc.txt</tt></pre>
</div></div>
<div class="paragraph">
<p>This next example will include <tt>docinfo.html</tt> and <tt>mydoc-docinfo.html</tt>
docinfo files in the HTML output file:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -a docinfo2 -b html4 mydoc.txt</tt></pre>
</div></div></div></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
width="100%"
frame="hsides"
cellspacing="0" cellpadding="4">
<col width="14%" />
<col width="14%" />
<col width="71%" />
<thead>
<tr>
<th align="left" valign="top">Name </th>
<th align="left" valign="top">Backends </th>
<th align="left" valign="top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><em><a id="X54"></a>encoding</em></p></td>
<td align="left" valign="top"><p class="table">html4, xhtml11, docbook</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Set the input and output document character set encoding. For example
the <tt>--attribute encoding=ISO-8859-1</tt> command-line option will set the
character set encoding to <tt>ISO-8859-1</tt>.</p>
</div>
<ul class="">
<li>
<span>
The default encoding is UTF-8.
</span>
</li>
<li>
<span>
This attribute specifies the character set in the output document.
</span>
</li>
<li>
<span>
The encoding name must correspond to a Python codec name or alias.
</span>
</li>
<li>
<span>
The <em>encoding</em> attribute can be set using an AttributeEntry inside
  the document header. For example:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>:encoding: ISO-8859-1</tt></pre>
</div></div>
</li>
</ul></div></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
width="100%"
frame="hsides"
cellspacing="0" cellpadding="4">
<col width="14%" />
<col width="14%" />
<col width="71%" />
<thead>
<tr>
<th align="left" valign="top">Name </th>
<th align="left" valign="top">Backends </th>
<th align="left" valign="top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><em><a id="X45"></a>icons</em></p></td>
<td align="left" valign="top"><p class="table">xhtml11</p></td>
<td align="left" valign="top"><div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em><a id="X45"></a>icons</em></p></td>
<td align="left" valign="top"><p class="table">xhtml11, html5</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Link admonition paragraph and admonition block icon images and badge
images. By default <em>icons</em> is undefined and text is used in place of
icon images.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em><a id="X44"></a>iconsdir</em></p></td>
<td align="left" valign="top"><p class="table">html4, html5, xhtml11, docbook</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>The name of the directory containing linked admonition and navigation
icons. Defaults to <tt>./images/icons</tt>.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>imagesdir</em></p></td>
<td align="left" valign="top"><p class="table">html4, html5, xhtml11, docbook</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>If this attribute is defined it is prepended to the target image file
name paths in inline and block image macros.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>keywords, description, title</em></p></td>
<td align="left" valign="top"><p class="table">html4, html5, xhtml11</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>The <em>keywords</em> and <em>description</em> attributes set the correspondingly
named HTML meta tag contents; the <em>title</em> attribute sets the HTML
title tag contents.  Their principle use is for SEO (Search Engine
Optimisation).  All three are optional, but if they are used they must
appear in the document header (or on the command-line). If <em>title</em> is
not specified the AsciiDoc document title is used.</p>
</div></div></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
width="100%"
frame="hsides"
cellspacing="0" cellpadding="4">
<col width="14%" />
<col width="14%" />
<col width="71%" />
<thead>
<tr>
<th align="left" valign="top">Name </th>
<th align="left" valign="top">Backends </th>
<th align="left" valign="top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><em>linkcss</em></p></td>
<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Link CSS stylesheets and JavaScripts. By default <em>linkcss</em> is
undefined in which case stylesheets and scripts are automatically
embedded in the output document.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>max-width</em></p></td>
<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Set the document maximum display width (sets the <em>body</em> element CSS
<em>max-width</em> property).</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>numbered</em></p></td>
<td align="left" valign="top"><p class="table">html4, html5, xhtml11, docbook (XSL Stylesheets)</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Adds section numbers to section titles. The <em>docbook</em> backend ignores
<em>numbered</em> attribute entries after the document header.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>plaintext</em></p></td>
<td align="left" valign="top"><p class="table">All backends</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>If this global attribute is defined all inline substitutions are
suppressed and block indents are retained.  This option is useful when
dealing with large amounts of imported plain text.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>quirks</em></p></td>
<td align="left" valign="top"><p class="table">xhtml11</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Include the <tt>xhtml11-quirks.conf</tt> configuration file and
<tt>xhtml11-quirks.css</tt> <a href="#X35">stylesheet</a> to work around IE6 browser
incompatibilities. This feature is deprecated and its use is
discouraged&#8201;&#8212;&#8201;documents are still viewable in IE6 without it.</p>
</div></div></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
width="100%"
frame="hsides"
cellspacing="0" cellpadding="4">
<col width="14%" />
<col width="14%" />
<col width="71%" />
<thead>
<tr>
<th align="left" valign="top">Name </th>
<th align="left" valign="top">Backends </th>
<th align="left" valign="top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><em>revremark</em></p></td>
<td align="left" valign="top"><p class="table">docbook</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>A short summary of changes in this document revision. Must be defined
prior to the first document section. The document also needs to be
dated to output this attribute.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>scriptsdir</em></p></td>
<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>The name of the directory containing linked JavaScripts.
See <a href="#X35">HTML stylesheets and JavaScript locations</a>.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>sgml</em></p></td>
<td align="left" valign="top"><p class="table">docbook45</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>The <tt>--backend=docbook45</tt> command-line option produces DocBook 4.5
XML.  You can produce the older DocBook SGML format using the
<tt>--attribute sgml</tt> command-line option.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>stylesdir</em></p></td>
<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>The name of the directory containing linked or embedded
<a href="#X35">stylesheets</a>.
See <a href="#X35">HTML stylesheets and JavaScript locations</a>.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>stylesheet</em></p></td>
<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>The file name of an optional additional CSS <a href="#X35">stylesheet</a>.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>theme</em></p></td>
<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Use alternative stylesheet (see <a href="#X35">Stylesheets</a>).</p>
</div></div></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">
<div class="sect1">
<script type="text/javascript">/*<![CDATA[*/subslide +=1;document.write("<h1 class='"+nextclass+"'>"+nexttitle+" ("+ subslide+")</h1>");slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">

<div class="tableblock">
<table rules="all"
width="100%"
frame="hsides"
cellspacing="0" cellpadding="4">
<col width="14%" />
<col width="14%" />
<col width="71%" />
<thead>
<tr>
<th align="left" valign="top">Name </th>
<th align="left" valign="top">Backends </th>
<th align="left" valign="top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><em><a id="X91"></a>toc</em></p></td>
<td align="left" valign="top"><p class="table">html5, xhtml11, docbook (XSL Stylesheets)</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Adds a table of contents to the start of an article or book document.
The <tt>toc</tt> attribute can be specified using the <tt>--attribute toc</tt>
command-line option or a <tt>:toc:</tt> attribute entry in the document
header. The <em>toc</em> attribute is defined by default when the <em>docbook</em>
backend is used. To disable table of contents generation undefine the
<em>toc</em> attribute by putting a <tt>:toc!:</tt> attribute entry in the document
header or from the command-line with an <tt>--attribute toc!</tt> option.</p>
</div>
<div class="paragraph">
<p><strong>xhtml11 and html5 backends</strong></p>
</div>
<ul class="">
<li>
<span>
JavaScript needs to be enabled in your browser.
</span>
</li>
<li>
<span>
The following example generates a numbered table of contents using a
  JavaScript embedded in the <tt>mydoc.html</tt> output document:
</span>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -a toc -a numbered mydoc.txt</tt></pre>
</div></div>
</li>
</ul></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>toc2</em></p></td>
<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Adds a scrollable table of contents in the left hand margin of an
article or book document. Use the <em>max-width</em> attribute to change the
content width. In all other respects behaves the same as the <em>toc</em>
attribute.</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>toc-title</em></p></td>
<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Sets the table of contents title (defaults to <em>Table of Contents</em>).</p>
</div></div></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><em>toclevels</em></p></td>
<td align="left" valign="top"><p class="table">html5, xhtml11</p></td>
<td align="left" valign="top"><div><div class="paragraph">
<p>Sets the number of title levels (1..4) reported in the table of
contents (see the <em>toc</em> attribute above). Defaults to 2 and must be
used with the <em>toc</em> attribute. Example usage:</p>
</div>
<div class="literalblock">
<div class="content">
<pre><tt>$ asciidoc -a toc -a toclevels=3 doc/asciidoc.txt</tt></pre>
</div></div></div></td>
</tr>
</tbody>
</table>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div><div class="slide">

<div class="sect1">
<h1 id="_license">Appendix I: License</h1>
<script type="text/javascript">/*<![CDATA[*/subslide=1;nextclass="sect1";nexttitle="License";slidefootnotes="";/*]]>*/</script>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc is free software; you can redistribute it and/or modify it
under the terms of the <em>GNU General Public License version 2</em> (GPLv2)
as published by the Free Software Foundation.</p>
</div>
<div class="paragraph">
<p>AsciiDoc is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License version 2 for more details.</p>
</div>
<div class="paragraph">
<p>Copyright &#169; 2002-2011 Stuart Rackham.</p>
</div>
<div id="footer" style="position: absolute; left: 5%; top: 80%; width: 90%;">
<div id="footer-text">
Last updated 2011-08-30 10:13:06 Paris, Madrid (heure d’été)
</div>
</div>
</div></div>
<script type="text/javascript">/*<![CDATA[*/if (slidefootnotes != ''){document.write("<hr/><p>"+slidefootnotes+"</p>");}/*]]>*/</script>
</div>
<script type="text/javascript">
/*<![CDATA[*/
    // move the div class="background" elements immediately
    // as document.body children
    var re = new RegExp("(^| )background\W*");
    var divs = document.body.getElementsByTagName("div");
    for (var i = (divs.length - 1); i >= 0 ; --i)
    {
      div = divs.item(i);
      if ( re.test(div.getAttribute("class")) )
      {
        div2 = div.cloneNode(true);
        div.parentNode.removeChild(div);
        document.body.appendChild(div2);
      }
    }
/*]]>*/
</script>
</body>
</html>
